gitxplain 0.1.8 → 0.2.0

package/.github/workflows/ci.yml

@@ -16,6 +16,8 @@ jobs:
         with:
           node-version: '20'
           cache: npm
+          registry-url: 'https://registry.npmjs.org'
+          always-auth: true
       - name: Install dependencies
         run: npm ci
       - name: Lint

package/.github/workflows/release.yml

@@ -2,12 +2,13 @@ name: Release
 on:
   push:
     tags:
-      - '*.*.*'
+      - 'v*'
+permissions:
+  contents: write
 jobs:
-  publish:
+  release:
+    if: startsWith(github.ref_name, 'v')
     runs-on: ubuntu-latest
-    permissions:
-      contents: read
     steps:
       - name: Checkout
         uses: actions/checkout@v4
@@ -16,12 +17,98 @@ jobs:
         with:
           node-version: '20'
           cache: npm
-          registry-url: 'https://registry.npmjs.org/'
+          registry-url: 'https://registry.npmjs.org'
+          always-auth: true
       - name: Install dependencies
         run: npm ci
+      - name: Derive release metadata
+        id: meta
+        run: |
+          VERSION="${GITHUB_REF_NAME#v}"
+          echo "version=${VERSION}" >> "${GITHUB_OUTPUT}"
+          echo "deb_path=dist/gitxplain_${VERSION}_all.deb" >> "${GITHUB_OUTPUT}"
       - name: Test
         run: npm test
+      - name: Build Debian package
+        run: ./scripts/build-deb.sh
+      - name: Verify npm token
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+        run: |
+          if [ -z "${NODE_AUTH_TOKEN}" ]; then
+            echo "NPM_TOKEN is not configured for this repository."
+            echo "Add it in GitHub: Settings -> Secrets and variables -> Actions -> New repository secret."
+            exit 1
+          fi
+          printf "//registry.npmjs.org/:_authToken=%s\n" "${NODE_AUTH_TOKEN}" > "${HOME}/.npmrc"
+          npm whoami
       - name: Publish to npm
         env:
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
         run: npm publish
+      - name: Compute npm tarball SHA-256
+        id: npm
+        run: |
+          VERSION="${{ steps.meta.outputs.version }}"
+          TARBALL_URL="https://registry.npmjs.org/gitxplain/-/gitxplain-${VERSION}.tgz"
+          curl -fsSL "${TARBALL_URL}" -o "gitxplain-${VERSION}.tgz"
+          SHA256="$(sha256sum "gitxplain-${VERSION}.tgz" | awk '{print $1}')"
+          echo "tarball_url=${TARBALL_URL}" >> "${GITHUB_OUTPUT}"
+          echo "sha256=${SHA256}" >> "${GITHUB_OUTPUT}"
+      - name: Checkout Homebrew tap
+        uses: actions/checkout@v4
+        with:
+          repository: guruswarupa/homebrew-tap
+          token: ${{ secrets.HOMEBREW_TAP_TOKEN }}
+          path: homebrew-tap
+      - name: Update Homebrew formula
+        run: |
+          VERSION="${{ steps.meta.outputs.version }}"
+          SHA256="${{ steps.npm.outputs.sha256 }}"
+          FORMULA_PATH="homebrew-tap/Formula/gitxplain.rb"
+          mkdir -p "$(dirname "${FORMULA_PATH}")"
+          cat > "${FORMULA_PATH}" <<EOF
+          class Gitxplain < Formula
+            desc "AI-powered Git commit explainer CLI"
+            homepage "https://github.com/guruswarupa/gitxplain"
+            url "https://registry.npmjs.org/gitxplain/-/gitxplain-${VERSION}.tgz"
+            sha256 "${SHA256}"
+            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
+          EOF
+      - name: Commit and push Homebrew tap changes
+        working-directory: homebrew-tap
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git add Formula/gitxplain.rb
+          if git diff --cached --quiet; then
+            echo "No Homebrew formula changes to commit."
+            exit 0
+          fi
+          git commit -m "gitxplain ${GITHUB_REF_NAME}"
+          git push
+      - name: Create GitHub release and upload Debian package
+        uses: softprops/action-gh-release@v2
+        with:
+          files: ${{ steps.meta.outputs.deb_path }}
+      - name: Print AUR update instructions
+        run: |
+          VERSION="${{ steps.meta.outputs.version }}"
+          SHA256="${{ steps.npm.outputs.sha256 }}"
+          echo "Manual AUR update steps:"
+          echo "1. Update packaging/aur/PKGBUILD with pkgver=${VERSION} and sha256sums=('${SHA256}')."
+          echo "2. Run: makepkg --printsrcinfo > .SRCINFO"
+          echo "3. Commit PKGBUILD and .SRCINFO to the AUR git repository and push."

package/README.md

@@ -10,18 +10,26 @@ Supported providers:
 - Gemini
 - Ollama
 - Chutes AI
+- Anthropic
+- Mistral
+- Azure OpenAI
 
 ## Features
 
 - 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 blame summaries, changelog drafting, PR description drafting, refactor suggestions, and test suggestion modes
+- Supports stash explanation and single-file diff deep dives
+- Supports merge conflict analysis with suggested resolutions
+- Supports cumulative token usage tracking and optional estimated cost reporting
+- Supports interactive split-plan review before history is rewritten
 - 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 release health status checks that show missing tags, unmerged version bumps, branch drift, and next steps
 - Supports AI-assisted commit planning for uncommitted working tree changes
 - Supports quick repository log output for full history inspection
-- Supports repository-aware CI/CD workflow generation for the repo you are currently in
+- Supports repository-aware CI/CD workflow generation for GitHub Actions, GitLab CI, CircleCI, and Bitbucket Pipelines
 - 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
@@ -38,6 +46,43 @@ Supported providers:
 - A Git repository in your current working directory
 - An API key for your chosen provider, or a local Ollama instance
 
+## Installation
+
+Install from npm:
+
+```bash
+npm install -g gitxplain
+```
+
+Install from bun:
+
+```bash
+bun install -g gitxplain
+```
+
+Install with Homebrew:
+
+```bash
+brew tap guruswarupa/homebrew-tap
+brew install gitxplain
+```
+
+Install from the AUR:
+
+```bash
+yay -S gitxplain
+```
+
+```bash
+paru -S gitxplain
+```
+
+Install from a Debian package downloaded from GitHub Releases:
+
+```bash
+sudo apt install ./gitxplain_<version>_all.deb
+```
+
 Optional advanced environment variables:
 
 - `LLM_PROVIDER` default: `openai`
@@ -70,6 +115,19 @@ Show the built-in command reference.
 gitxplain --help
 ```
 
+Inspect cache usage or clear cached responses.
+
+```bash
+gitxplain cache stats
+gitxplain cache clear
+```
+
+Show cumulative token usage and estimated cost totals.
+
+```bash
+gitxplain --cost
+```
+
 Save the default AI provider.
 
 ```bash
@@ -142,6 +200,13 @@ Preview or create release tags.
 gitxplain --tag
 ```
 
+Explain the latest stash, or a specific stash entry.
+
+```bash
+gitxplain --stash
+gitxplain --stash stash@{2}
+```
+
 Print repository log output.
 
 ```bash
@@ -160,6 +225,21 @@ Detect and generate CI/CD workflow files.
 gitxplain --pipeline
 ```
 
+Analyze unresolved merge conflicts in the working tree.
+
+```bash
+gitxplain --conflict
+gitxplain --conflict --diff src/auth.js
+```
+
+Install a git hook for commit, merge, or push workflows.
+
+```bash
+gitxplain install-hook
+gitxplain install-hook post-merge
+gitxplain install-hook pre-push
+```
+
 Analysis:
 
 Generate a one-line summary.
@@ -210,6 +290,48 @@ Focus on security-relevant changes.
 --security
 ```
 
+Suggest refactoring follow-ups.
+
+```bash
+--refactor
+```
+
+Suggest tests to add or update.
+
+```bash
+--test-suggest
+```
+
+Generate a PR description.
+
+```bash
+--pr-description
+```
+
+Generate changelog-style notes.
+
+```bash
+--changelog
+```
+
+Analyze file ownership with git blame.
+
+```bash
+--blame <file>
+```
+
+Suggest resolutions for unresolved merge conflicts.
+
+```bash
+--conflict
+```
+
+Focus analysis on one changed file.
+
+```bash
+--diff <file>
+```
+
 Propose splitting a commit into smaller commits.
 
 ```bash
@@ -234,6 +356,12 @@ Preview a plan without applying it.
 --dry-run
 ```
 
+Review or edit a split plan before execution.
+
+```bash
+--interactive
+```
+
 Release:
 
 Show release status details.
@@ -398,6 +526,18 @@ Stream model output as it arrives.
 --stream
 ```
 
+Bypass cached responses for one command.
+
+```bash
+--no-cache
+```
+
+Show cumulative token usage and estimated cost totals.
+
+```bash
+--cost
+```
+
 Limit diff size before sending it to the model.
 
 ```bash
@@ -423,6 +563,17 @@ gitxplain a1b2c3d --summary
 gitxplain HEAD~1 --lines
 gitxplain HEAD~5..HEAD --markdown
 gitxplain --branch main --review
+gitxplain --branch main --pr-description
+gitxplain HEAD~10..HEAD --changelog
+gitxplain HEAD --refactor
+gitxplain HEAD --test-suggest
+gitxplain --blame cli/index.js
+gitxplain --conflict
+gitxplain --stash
+gitxplain HEAD~5..HEAD --lines --diff cli/index.js
+gitxplain --cost
+gitxplain HEAD --split --interactive --execute
+gitxplain install-hook post-merge
 ```
 
 If you do not want to link it globally, you can still run it locally:
@@ -441,14 +592,24 @@ node ./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
+- `--refactor`: suggest maintainability-focused refactors visible in the change
+- `--test-suggest`: suggest the most valuable tests to add or update
+- `--pr-description`: draft a ready-to-paste pull request description
+- `--changelog`: generate changelog-style release notes from the change set
+- `--blame <file>`: summarize ownership and change history for one file using `git blame`
+- `--conflict`: inspect unresolved merge conflicts and suggest likely resolutions
+- `--stash [ref]`: explain what is stored in a stash entry, defaulting to `stash@{0}`
+- `--diff <file>`: focus commit or range analysis on a single file
 - `--split`: propose how to split a commit into multiple atomic commits
+- `--interactive`: review or edit a split plan before executing it
+- `--cost`: show cumulative token usage and estimated cost totals
 - `--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
 - `--release [status]`: inspect release branch health, missing tags, source-vs-release drift, and the next recommended action
 - `--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
-- `--pipeline`: inspect the current repository and generate GitHub Actions CI/CD workflows
+- `--pipeline`: inspect the current repository and generate GitHub Actions, GitLab CI, CircleCI, or Bitbucket Pipelines config
 - `--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
@@ -471,6 +632,9 @@ Run a few common Git actions directly through `gitxplain`:
 
 ```bash
 gitxplain --status
+gitxplain cache stats
+gitxplain cache clear
+gitxplain --cost
 gitxplain add README.md
 gitxplain remove README.md
 gitxplain remove hard
@@ -538,13 +702,19 @@ Actually split the current `HEAD` commit into smaller commits:
 gitxplain HEAD --split --execute
 ```
 
+Review the plan interactively before executing it:
+
+```bash
+gitxplain HEAD --split --interactive --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.
+`--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. Adding `--interactive` lets you keep, edit, skip, or abort individual split groups before the rewrite happens.
 
 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.
 
@@ -631,7 +801,7 @@ gitxplain config set model gpt-4.1-mini
 gitxplain config list
 ```
 
-## Clipboard, Streaming, And Hooks
+## Clipboard, Streaming, Cost, And Hooks
 
 Copy the final output to your clipboard:
 
@@ -645,12 +815,30 @@ Stream long responses as they arrive:
 gitxplain HEAD~1 --full --stream
 ```
 
+Show cumulative usage and estimated cost totals:
+
+```bash
+gitxplain --cost
+```
+
 Install a post-commit hook that saves a Markdown explanation under `.git/gitxplain/last-explanation.md`:
 
 ```bash
 gitxplain install-hook
 ```
 
+Install a post-merge hook that explains the new `HEAD` after merges:
+
+```bash
+gitxplain install-hook post-merge
+```
+
+Install a pre-push hook that runs a security-oriented review:
+
+```bash
+gitxplain install-hook pre-push
+```
+
 ## Provider Setup
 
 Recommended persistent setup:
@@ -673,6 +861,41 @@ gitxplain config set provider groq
 gitxplain config set api-key your_key
 ```
 
+Additional supported providers:
+
+```bash
+gitxplain config set provider anthropic
+gitxplain config set api-key your_key
+
+gitxplain config set provider mistral
+gitxplain config set api-key your_key
+
+gitxplain config set provider azure-openai
+gitxplain config set api-key your_key
+```
+
+Azure OpenAI also requires endpoint configuration:
+
+```bash
+export AZURE_OPENAI_BASE_URL="https://your-resource.openai.azure.com"
+export AZURE_OPENAI_DEPLOYMENT="your-deployment-name"
+export AZURE_OPENAI_API_VERSION="2024-10-21"
+```
+
+Optional token pricing env vars for estimated cost tracking:
+
+```bash
+export OPENAI_INPUT_COST_PER_MTOK="0.15"
+export OPENAI_OUTPUT_COST_PER_MTOK="0.60"
+```
+
+Or use generic pricing defaults across providers:
+
+```bash
+export LLM_INPUT_COST_PER_MTOK="0.15"
+export LLM_OUTPUT_COST_PER_MTOK="0.60"
+```
+
 If you want to inspect what is saved:
 
 ```bash