@g-abhishek/gitx 0.1.2 → 0.1.5

package/README.md

@@ -1,12 +1,395 @@
 # gitx
 
-AI-powered Git workflow automation CLI and SDK (WIP).
+**AI-powered Git workflow automation CLI and SDK.**
 
-## Getting started
+gitx wraps your everyday git operations with AI to generate commit messages, write PR descriptions, review code, resolve merge conflicts, implement tasks from a plain-English prompt, and answer questions about your repo — all from a single CLI.
+
+---
+
+## Table of Contents
+
+- [Features](#features)
+- [Installation](#installation)
+- [Configuration](#configuration)
+- [Commands](#commands)
+  - [gitx ask](#gitx-ask)
+  - [gitx commit](#gitx-commit)
+  - [gitx push](#gitx-push)
+  - [gitx sync](#gitx-sync)
+  - [gitx implement](#gitx-implement)
+  - [gitx pr create](#gitx-pr-create)
+  - [gitx pr review](#gitx-pr-review)
+  - [gitx pr resolve](#gitx-pr-resolve)
+  - [gitx pr merge](#gitx-pr-merge)
+  - [gitx pr list](#gitx-pr-list)
+  - [gitx pr close](#gitx-pr-close)
+  - [gitx config](#gitx-config)
+- [Supported Providers](#supported-providers)
+- [Environment Variables](#environment-variables)
+
+---
+
+## Features
+
+| Feature | What it does |
+|---------|--------------|
+| **AI commit messages** | Generates conventional-commit messages from your staged diff |
+| **AI PR descriptions** | Writes PR title + body from your branch commits and diff |
+| **AI code review** | Senior-dev quality review with inline comments posted to GitHub/GitLab/Azure (`gitx pr review`) |
+| **AI comment resolve** | Reads unresolved review comments, fixes them in code, commits and pushes (`gitx pr resolve`) |
+| **AI conflict resolution** | Tries to auto-resolve merge/rebase conflicts; prompts when unsure |
+| **AI task implementation** | Takes a plain-English task, plans and applies diffs, commits, pushes, opens PR |
+| **gitx ask** | Ask anything about your repo — get answers grounded in live git context |
+
+---
+
+## Installation
 
 ```bash
+# Clone and build
+git clone https://github.com/g-abhishek/gitx.git
+cd gitx
 npm install
 npm run build
-node dist/bin.js --help
+
+# Link globally so `gitx` is available everywhere
+npm link
+```
+
+**Requirements:** Node.js ≥ 18
+
+---
+
+## Configuration
+
+Run the interactive setup wizard on first use:
+
+```bash
+gitx init
+# or equivalently:
+gitx config setup
+```
+
+The wizard will ask you to configure:
+
+1. **Git provider** — GitHub, GitLab, or Azure DevOps
+2. **AI provider** — Anthropic Claude (API key), OpenAI (API key), or local Claude CLI (no key needed)
+
+Config is stored in `~/.config/gitx/config.json` (or the platform-appropriate XDG path).
+
+**Quick config with env vars (no wizard needed):**
+
+```bash
+export ANTHROPIC_API_KEY=sk-ant-…   # enables Claude automatically
+export OPENAI_API_KEY=sk-…          # enables OpenAI automatically
+```
+
+### Azure DevOps authentication
+
+Azure DevOps supports two authentication methods:
+
+| Method | When to use |
+|--------|-------------|
+| **GCM (recommended)** | Your company uses Git Credential Manager + OAuth (blocks PAT tokens) |
+| **PAT** | Personal Access Token — classic approach, works everywhere |
+
+**GCM setup (one time):**
+
+```bash
+# 1. Configure git to use OAuth for Azure DevOps
+git config --global credential.azreposCredentialType oauth
+git config --global credential.https://dev.azure.com.useHttpPath true
+
+# 2. Run gitx setup — choose "Azure DevOps" → "GCM"
+gitx config set azure
+# gitx verifies your GCM setup and saves authMethod: "gcm" — no token stored
+```
+
+With GCM configured, gitx calls `git credential fill` at runtime to obtain a short-lived OAuth token. GCM handles browser login (once) and silent token refresh automatically.
+
+---
+
+## Commands
+
+### gitx ask
+
+Acts as a smart support assistant that can answer three categories of question — all in one command.
+
+```bash
+gitx ask "<question>"
+gitx ask "<question>" --pr     # also fetch open PRs for context
+```
+
+**1. Setup & diagnostic questions** — answered from your live gitx config (no fabrication):
+
+```bash
+gitx ask "is my AI provider set up?"
+gitx ask "which AI model am I using?"
+gitx ask "do I have a GitHub token configured?"
+gitx ask "why isn't gitx working?"
+```
+
+**2. Repo state questions** — answered from live git data:
+
+```bash
+gitx ask "what did I last commit?"
+gitx ask "do I have any unstaged changes?"
+gitx ask "show me all open PRs" --pr
+gitx ask "do I have any stashed changes?"
+```
+
+**3. How-to questions** — answered from the built-in command reference:
+
+```bash
+gitx ask "how do I sync my branch with main?"
+gitx ask "how do I undo my last commit without losing changes?"
+gitx ask "what command creates a PR?"
+gitx ask "how do I implement a task with AI?"
+```
+
+**Sources the AI draws from:**
+
+- **Live gitx config** — which AI provider is active, whether keys are set, which git providers have tokens (keys are never exposed, only their presence/absence)
+- **Live git state** — current branch, last 10 commits, working-tree status, stash list
+- **Open PRs** — fetched from the provider API when `--pr` is passed or the question mentions "PR"
+- **Built-in command reference** — the full gitx command table is embedded in every prompt
+
+---
+
+### gitx commit
+
+Stage all changes, AI-generate a conventional-commit message from the diff, preview it, and commit.
+
+```bash
+gitx commit                    # stage → AI message → confirm → commit
+gitx commit -m "feat: …"       # skip AI, use your own message
+gitx commit --push             # commit then push to origin
+gitx commit --dry-run          # preview the AI message without committing
+```
+
+The AI always receives a `git diff --stat` file summary alongside the diff, so it sees every changed file even when the diff is large and gets truncated.
+
+---
+
+### gitx push
+
+Stage → AI-commit → push in one command.
+
+```bash
+gitx push
+gitx push -b feature/my-branch   # push to a specific branch name
+gitx push --staged                # commit only already-staged files (skip git add -A)
+gitx push --dry-run               # preview without pushing
+```
+
+Use `--staged` when you've manually staged a subset of changes with `git add` and want the AI commit message to reflect only those changes.
+
+---
+
+### gitx sync
+
+Sync your current branch with its base branch. Auto-detects the base branch, fetches from origin, then merges or rebases.
+
+```bash
+gitx sync                              # auto-detect base, merge (default)
+gitx sync --strategy rebase            # rebase instead of merge
+gitx sync --base develop               # explicitly set the base branch
+gitx sync --continue                   # resume after manually resolving conflicts
+gitx sync --abort                      # cancel an in-progress operation
+```
+
+**AI conflict resolution:** When a merge/rebase conflict is detected, gitx asks the AI to resolve it. High-confidence resolutions are applied automatically; low-confidence ones are shown to you for confirmation.
+
+**Pre-sync PR comment check:** If your branch has an open PR with unresolved review comments, gitx will ask whether to address them before syncing. Choosing "Resolve comments first" runs the address workflow, commits the fixes, then the sync rebase/merge picks everything up in a single push.
+
+---
+
+### gitx port
+
+Port commits from your current branch onto one or more other branches — the solution to "my lead wants this change on two other branches too."
+
+gitx uses `git cherry` (patch-ID comparison) to detect which commits are already ported, so re-running is always safe and incremental.
+
+```bash
+# From your feature branch:
+gitx port release/v2                    # port to one branch
+gitx port release/v2 hotfix/v1         # port to multiple at once
+gitx port release/v2 --base develop    # override base branch detection
+gitx port release/v2 --no-pr           # push only, create PRs manually
+gitx port release/v2 --draft           # create draft PRs
+
+# After adding more commits — only NEW commits will be ported:
+gitx port release/v2                   # incremental: skips already-ported commits
+
+# Conflict resolution:
+gitx port --continue                   # after manually fixing conflicts
+gitx port --abort                      # abandon a stuck port
+```
+
+**What it does per target branch:**
+1. Checks `origin/<target>` exists — errors clearly if not
+2. On first run: creates `port/<source>-to-<target>` and cherry-picks all commits
+3. On re-run: uses `git cherry` to find only NEW commits — skips already-ported ones
+4. Conflicts → AI attempts resolution; unresolvable ones pause for manual fix
+5. Pushes the port branch, checks for an existing open PR (updates it), or creates a new one with an AI-generated description
+
+---
+
+### gitx implement
+
+Give the AI a task in plain English. It analyzes the repo, creates a plan, generates and applies diffs, commits, pushes, and opens a PR.
+
+```bash
+gitx implement "add pagination to the users endpoint"
+gitx implement "fix the null pointer on login" --mode guided
+gitx implement "refactor auth module" --mode plan    # plan only, no code changes
+gitx implement "add unit tests for utils" --dry-run  # preview plan, no commits
+```
+
+**Autonomy modes:**
+
+| Mode | Behaviour |
+|------|-----------|
+| `plan` | Analyze and generate a plan — no code changes |
+| `guided` | Confirm after every AI step |
+| `semi-auto` | Confirm once before execution begins |
+| `auto` | Fully automatic end-to-end |
+
+---
+
+### gitx pr create
+
+Stage any uncommitted changes, AI-generate a PR title and body from your branch commits and diff, and open the PR.
+
+```bash
+gitx pr create
+gitx pr create --title "feat: …" --body "…"   # override AI-generated content
+gitx pr create --draft                          # open as draft PR
+gitx pr create --dry-run                        # preview without creating
 ```
 
+---
+
+### gitx pr review
+
+Run a senior-developer quality AI review on an open PR and post the results as formal review comments (inline where supported).
+
+```bash
+gitx pr review <number>
+gitx pr review 42 --no-comment    # show review locally, don't post to PR
+gitx pr review 42 --inline        # force inline comments (skip plain-comment fallback)
+```
+
+The review covers: correctness, security, robustness, performance, breaking changes, best practices, test coverage, and documentation. After reviewing, run `gitx pr resolve <number>` to AI-fix the comments in your code.
+
+---
+
+### gitx pr resolve
+
+Read all unresolved review comments on a PR, AI-generate targeted code fixes for each, and apply them.
+
+```bash
+gitx pr resolve <number>                  # apply fixes, commit, and push
+gitx pr resolve 42 --no-commit           # apply fixes to working tree only — review before committing
+gitx pr resolve 42 --no-push            # apply and commit locally, skip push
+gitx pr resolve 42 --dry-run            # preview what would be fixed, nothing applied
+```
+
+**Typical workflow:**
+```bash
+gitx pr review 42       # AI reviews and posts inline comments to the PR
+# ... read the comments, understand the feedback ...
+gitx pr resolve 42      # AI fixes the comments in your code and pushes
+```
+
+Use `--no-commit` when you want to inspect the AI-applied diffs with `git diff` before deciding to commit.
+
+---
+
+### gitx pr merge
+
+Merge a pull request via the provider API.
+
+```bash
+gitx pr merge <number>
+gitx pr merge 42 --strategy rebase       # rebase merge
+gitx pr merge 42 --strategy merge        # regular merge commit
+gitx pr merge 42 --delete-branch        # delete source branch after merge
+gitx pr merge 42 --force                 # skip confirmation prompt
+```
+
+Default strategy: `squash`.
+
+---
+
+### gitx pr list
+
+List pull requests for the current repo.
+
+```bash
+gitx pr list                    # open PRs (default)
+gitx pr list --state closed
+gitx pr list --state all
+```
+
+---
+
+### gitx pr close
+
+Close (or abandon on Azure DevOps) a pull request.
+
+```bash
+gitx pr close <number>
+gitx pr close 42 --force    # skip confirmation prompt
+```
+
+---
+
+### gitx config
+
+Manage your gitx configuration.
+
+```bash
+gitx config                         # run interactive setup wizard
+gitx config setup                   # same as above
+gitx config show                    # display current config (secrets redacted)
+gitx config set github              # configure GitHub token
+gitx config set openai              # configure OpenAI API key
+gitx config set-default-ai claude   # switch AI provider
+gitx config set-default-branch main # set default base branch
+```
+
+---
+
+## Supported Providers
+
+| Type | Supported |
+|------|-----------|
+| **Git hosts** | GitHub, GitLab, Azure DevOps |
+| **Azure auth** | PAT (Personal Access Token), GCM OAuth (Git Credential Manager) |
+| **AI backends** | Anthropic Claude (API), OpenAI GPT-4o, Local Claude CLI |
+
+---
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `ANTHROPIC_API_KEY` | Anthropic API key — auto-selects Claude as the AI provider |
+| `OPENAI_API_KEY` | OpenAI API key — auto-selects OpenAI as the AI provider |
+| `GITX_AI_MODEL` | Override the AI model name (e.g. `claude-opus-4-5`, `gpt-4-turbo`) |
+| `GITX_DEBUG=1` | Print full stack traces on errors |
+
+AI provider priority when multiple are configured:
+1. `ANTHROPIC_API_KEY` env var → Claude
+2. `OPENAI_API_KEY` env var → OpenAI
+3. `defaultAiProvider` in config
+4. First configured provider entry with a key
+5. Auto-detected local `claude` CLI
+6. Mock fallback (warns user)
+
+---
+
+## License
+
+MIT

package/dist/ai/claudeAi.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Claude AI integration via the Anthropic Messages API.
+ *
+ * Authentication: reads ANTHROPIC_API_KEY from the environment.
+ * Model:          defaults to claude-3-5-haiku-20241022 (fast, affordable).
+ *                 Override via GITX_AI_MODEL env var.
+ *
+ * All methods send a structured system prompt and parse the JSON response.
+ * If parsing fails we fall back gracefully rather than crashing.
+ */
+import type { AiAnalyzeTaskResponse, AiClient, AiGenerateDiffsResponse, AiGeneratePlanResponse, AiReviewPRResponse, AiSuggestFixesResponse, AiSummarizeChangesResponse } from "./types.js";
+export declare class ClaudeAi implements AiClient {
+    private readonly apiKey;
+    private readonly model;
+    /**
+     * @param apiKey  Anthropic API key. Falls back to ANTHROPIC_API_KEY env var.
+     * @param model   Model override. Falls back to GITX_AI_MODEL env var then default.
+     */
+    constructor(apiKey?: string, model?: string);
+    /** Check whether an API key is available without instantiating the class. */
+    static isAvailable(key?: string): boolean;
+    analyzeTask(input: string): Promise<AiAnalyzeTaskResponse>;
+    generatePlan(context: unknown): Promise<AiGeneratePlanResponse>;
+    generateDiffs(step: unknown): Promise<AiGenerateDiffsResponse>;
+    summarizeChanges(diff: unknown): Promise<AiSummarizeChangesResponse>;
+    suggestFixes(comment: unknown): Promise<AiSuggestFixesResponse>;
+    reviewPR(context: unknown): Promise<AiReviewPRResponse>;
+    generatePrContent(commits: string[], diff: string, stat?: string): Promise<import("./types.js").AiPrContentResponse>;
+    resolveConflict(filePath: string, conflictContent: string): Promise<import("./types.js").AiConflictResolutionResponse>;
+    generateCommitMessage(diff: string): Promise<import("./types.js").AiCommitMessageResponse>;
+    reviewPRDetailed(context: Parameters<import("./types.js").AiClient["reviewPRDetailed"]>[0]): Promise<import("./types.js").AiDetailedReviewResponse>;
+    generateFix(context: Parameters<import("./types.js").AiClient["generateFix"]>[0]): Promise<import("./types.js").AiFixResponse>;
+    ask(question: string, context: import("./types.js").AiAskContext): Promise<import("./types.js").AiAskResponse>;
+}
+//# sourceMappingURL=claudeAi.d.ts.map

package/dist/ai/claudeAi.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"claudeAi.d.ts","sourceRoot":"","sources":["../../src/ai/claudeAi.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,OAAO,KAAK,EACV,qBAAqB,EACrB,QAAQ,EACR,uBAAuB,EACvB,sBAAsB,EACtB,kBAAkB,EAClB,sBAAsB,EACtB,0BAA0B,EAC3B,MAAM,YAAY,CAAC;AA+FpB,qBAAa,QAAS,YAAW,QAAQ;IACvC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAE/B;;;OAGG;gBACS,MAAM,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM;IAY3C,6EAA6E;IAC7E,MAAM,CAAC,WAAW,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO;IAInC,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,qBAAqB,CAAC;IAqB1D,YAAY,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,sBAAsB,CAAC;IA8C/D,aAAa,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,uBAAuB,CAAC;IAuD9D,gBAAgB,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,0BAA0B,CAAC;IAgCpE,YAAY,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,sBAAsB,CAAC;IA+C/D,QAAQ,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAoDvD,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,YAAY,EAAE,mBAAmB,CAAC;IAmCpH,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,YAAY,EAAE,4BAA4B,CAAC;IA+BtH,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,YAAY,EAAE,uBAAuB,CAAC;IA+B1F,gBAAgB,CACpB,OAAO,EAAE,UAAU,CAAC,OAAO,YAAY,EAAE,QAAQ,CAAC,kBAAkB,CAAC,CAAC,CAAC,CAAC,CAAC,GACxE,OAAO,CAAC,OAAO,YAAY,EAAE,wBAAwB,CAAC;IAWnD,WAAW,CACf,OAAO,EAAE,UAAU,CAAC,OAAO,YAAY,EAAE,QAAQ,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC,GACnE,OAAO,CAAC,OAAO,YAAY,EAAE,aAAa,CAAC;IAWxC,GAAG,CACP,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,OAAO,YAAY,EAAE,YAAY,GACzC,OAAO,CAAC,OAAO,YAAY,EAAE,aAAa,CAAC;CAK/C"}