@ateriss_/aiv-cli 1.0.1 → 1.0.3

package/README.md

@@ -1,26 +1,54 @@
 # aiv — AI PR Reviewer
 
-A local-first, multi-agent CLI for reviewing GitHub pull requests using any supported AI provider. Runs three specialized agents in parallel (Business, Architecture, Security) and produces a structured risk report with findings, suggestions, and an executive summary.
-
 ```
  █████╗ ██╗    ██████╗ ██████╗     ██████╗ ███████╗██╗   ██╗██╗███████╗██╗    ██╗███████╗██████╗
 ██╔══██╗██║    ██╔══██╗██╔══██╗    ██╔══██╗██╔════╝██║   ██║██║██╔════╝██║    ██║██╔════╝██╔══██╗
 ███████║██║    ██████╔╝██████╔╝    ██████╔╝█████╗  ██║   ██║██║█████╗  ██║ █╗ ██║█████╗  ██████╔╝
 ██╔══██║██║    ██╔═══╝ ██╔══██╗    ██╔══██╗██╔══╝  ╚██╗ ██╔╝██║██╔══╝  ██║███╗██║██╔══╝  ██╔══██╗
 ██║  ██║██║    ██║     ██║  ██║    ██║  ██║███████╗ ╚████╔╝ ██║███████╗╚███╔███╔╝███████╗██║  ██║
-╚═╝  ╚═╝╚═╝    ╚═╝     ╚═╝  ╚═╝    ╚═╝  ╚═╝╚══════╝  ╚═══╝  ╚═╝╚══════╝ ╚══╝╚══╝ ╚══════╝╚═╝  ╚═╝`;
+╚═╝  ╚═╝╚═╝    ╚═╝     ╚═╝  ╚═╝    ╚═╝  ╚═╝╚══════╝  ╚═══╝  ╚═╝╚══════╝ ╚══╝╚══╝ ╚══════╝╚═╝  ╚═╝
 
    by Ateriss
 ```
 
 ---
 
+## What is aiv?
+
+Code review is one of the most important quality gates in a software team — and also one of the most time-consuming. Reviewers need to understand the business context, track architectural decisions, spot security risks, and catch regressions, all while reading through a diff that may span dozens of files.
+
+**aiv** is a local-first CLI that runs that analysis for you, before a human ever opens the PR.
+
+It sends the diff to three specialized AI agents in parallel — one focused on **business logic and domain rules**, one on **architecture and structural patterns**, and one on **security vulnerabilities** — and returns a structured risk report with severity-rated findings, specific suggestions per file, and an executive summary. The report is anchored to your project: aiv reads your `context.md` (project background, architecture decisions, sensitive zones) and `rules.yml` (custom business rules, required calls, forbidden patterns) so findings are relevant to your codebase, not just generic linting advice.
+
+**What aiv catches that linters miss:**
+
+- A retry loop that could cause duplicate charges because it skips the idempotency check your team agreed on
+- A service that imports directly from a handler, breaking the layer contract
+- A new endpoint that reads user data without going through the authorization middleware
+- A payroll mutation that doesn't call `auditLog()` as required by your rules
+- A function moved to a shared module that now exposes internal state to layers that shouldn't see it
+
+**Two perspectives, one tool:**
+
+aiv covers both sides of the code review workflow. As a **reviewer**, run `aiv review` to analyze an open PR and act directly from the terminal — approve, request changes, post the report as a comment, or merge. As the **author**, run `aiv check` before opening a PR to catch issues in your own branch first. If the report looks good, create the PR directly from the terminal; if not, save a `.aiv/checklist.md` with all findings as checkboxes so you know exactly what to fix.
+
+**What happens after the review:**
+
+Once the report is in, aiv lets you act on it directly from the terminal — approve the PR, request changes, post the full report as a formatted GitHub comment, or merge with your preferred strategy (squash, merge, rebase). If you've already reviewed the PR in a previous session, aiv detects the cached analysis in the PR comments and asks if you want to reuse it instead of re-running the agents.
+
+**Works with any AI provider.** Claude, OpenAI, Gemini, Groq, Mistral, DeepSeek, Kimi, Ollama, or any OpenAI-compatible endpoint. Mix providers per agent — use a fast model for routine checks and a powerful one for security. Configure a fallback chain so a quota error on one provider silently switches to the next without losing the run.
+
+---
+
 ## Table of Contents
 
 - [Requirements](#requirements)
 - [Installation](#installation)
 - [Quick Start](#quick-start)
 - [Commands Reference](#commands-reference)
+  - [aiv review](#aiv-review)
+  - [aiv check](#aiv-check)
 - [Configuration](#configuration)
   - [Global Config](#global-config)
   - [Repo Config](#repo-config)
@@ -100,13 +128,22 @@ aiv context generate
 aiv prs
 ```
 
-**5. Review a PR:**
+**5. Review a PR (as a reviewer):**
 
 ```bash
 aiv review 42
 ```
 
-After the report, aiv asks if you want to **approve**, **request changes**, or **merge** directly on GitHub.
+After the report, aiv asks if you want to approve, request changes, post the report as a PR comment, or merge directly from the terminal.
+
+**Or: analyze your own branch before opening a PR (as the author):**
+
+```bash
+aiv check           # compares current branch vs origin/main (auto-detected)
+aiv check qa        # compares current branch vs origin/qa
+```
+
+After the report, aiv asks: create the PR on GitHub or save a checklist of findings to `.aiv/checklist.md`.
 
 ---
 
@@ -120,7 +157,8 @@ Every command has a short alias. Long and short forms are identical.
 |-----------|-------|-------------|
 | `aiv init` | `aiv i` | Initialize aiv globally and in the current repo |
 | `aiv prs` | `aiv p` | List open PRs, then optionally review one |
-| `aiv review [pr-number]` | `aiv r` | Review a PR or pick interactively |
+| `aiv review [pr-number]` | `aiv r` | Review a PR or pick interactively (reviewer perspective) |
+| `aiv check [base-branch]` | `aiv c` | Analyze local diff before opening a PR (author perspective) |
 | `aiv agents` | `aiv a` | List available agents and their focus areas |
 
 ### Context
@@ -207,7 +245,64 @@ aiv review 42 --agent business architecture
 aiv review 42 --json          # raw JSON, no interactive prompt
 ```
 
-After the report prints, aiv asks whether to **approve**, **request changes**, or **skip** — and submits the decision directly to GitHub. If you approve, you can optionally merge the PR right away and choose the merge strategy. `context.md` and `tree.json` are always refreshed after an approval.
+If a previous aiv analysis exists as a comment on the PR, aiv asks whether to reuse it or run a fresh analysis. After the report, the post-review action menu lets you approve, request changes, post the report as a comment, or skip.
+
+---
+
+### `aiv check`
+
+Analyzes your local branch against a remote base branch **before** opening a PR — the author's equivalent of `aiv review`.
+
+```bash
+aiv check              # auto-detects base (origin/main, origin/master, origin/develop)
+aiv c
+
+aiv check qa           # compare current branch vs origin/qa
+aiv check main         # compare current branch vs origin/main
+aiv check --agent security           # run only the security agent
+aiv check qa --json                  # raw JSON output
+```
+
+The diff is always computed against the **remote** branch (`origin/<base>`), not your local copy, so findings reflect the actual gap that would be in the PR.
+
+After the report, aiv detects whether your branch has unpushed commits and adjusts the menu accordingly:
+
+```
+# If there are unpushed commits:
+? What would you like to do?
+❯ 🚀  Push y crear PR en GitHub
+  📋  Guardar checklist en .aiv/
+  ────────────────────────────────────────
+  ↩  Skip
+
+# If the branch is already up to date with the remote:
+? What would you like to do?
+❯ 🚀  Crear PR en GitHub
+  📋  Guardar checklist en .aiv/
+  ────────────────────────────────────────
+  ↩  Skip
+```
+
+- **Push y crear PR** — runs `git push origin <branch>`, then creates the PR via GitHub API. If the push fails, it stops before attempting PR creation.
+- **Crear PR** — branch is already pushed; creates the PR directly without a push.
+- **Guardar checklist** — writes `.aiv/checklist.md` with all findings as `- [ ]` checkboxes, grouped by severity. The `.aiv/` folder is gitignored so the file never reaches the remote.
+
+**Example checklist (`aiv/checklist.md`):**
+
+```markdown
+# aiv Check: feature/payments → main
+Generated: 2026-05-18  |  Risk: HIGH (74/100)
+
+## Critical & High
+
+- [ ] **[HIGH]** Missing idempotency key on retry — `src/payments/retry.ts`
+  > Pass a stable key derived from the original transaction ID.
+- [ ] **[CRITICAL]** auditLog() not called in retry path
+
+## Medium
+
+- [ ] **[MEDIUM]** Direct database write outside billing module — `src/db/payments.ts`
+```
 
 ---
 
@@ -359,13 +454,15 @@ business_rules:
       - directDbWrite
 ```
 
+The more specific your rules, the fewer false positives and the more actionable the findings.
+
 ---
 
 ### Context
 
 `.aiv/context.md` — project background that agents read before analyzing the diff.
 
-Auto-generated by `aiv init`, `aiv context refresh`, and `aiv context generate`. You can edit it freely — custom sections are preserved on the next refresh.
+Auto-generated by `aiv init`, `aiv context refresh`, and `aiv context generate`. You can edit it freely — the richer this file, the more accurate the findings.
 
 ```markdown
 ## Business Context
@@ -385,8 +482,6 @@ Services must not import from handlers.
 - src/payments/ — Stripe integration, never bypass PaymentGateway
 ```
 
-The richer this file, the more accurate the agent findings.
-
 ---
 
 ## GitHub Account Management
@@ -489,7 +584,7 @@ gemini:
 
 ### OpenAI-compatible providers
 
-Any provider that exposes an OpenAI-compatible API can be registered with one command — no code changes, no updates needed when new providers launch.
+Any provider that exposes an OpenAI-compatible API can be registered with one command — no code changes needed when new providers launch.
 
 ```bash
 # Kimi (Moonshot AI)
@@ -527,12 +622,6 @@ aiv config add-provider ollama \
   --base-url http://localhost:11434/v1 \
   --api-key-env OLLAMA_API_KEY \
   --model llama3.2
-
-# Any future provider that adopts the OpenAI spec
-aiv config add-provider newprovider \
-  --base-url https://api.newprovider.com/v1 \
-  --api-key-env NEWPROVIDER_API_KEY \
-  --model their-model-name
 ```
 
 Once registered, custom providers work exactly like built-ins:
@@ -551,7 +640,6 @@ aiv config add-provider kimi --model moonshot-v1-32k --force  # update
 Each agent (and the context generator) can use a different provider or model:
 
 ```bash
-# Assign provider/model per agent
 aiv config set-agent-provider business    claude/claude-sonnet-4-6
 aiv config set-agent-provider security    openai/gpt-4.1
 aiv config set-agent-provider architecture gemini/gemini-2.0-flash
@@ -569,8 +657,6 @@ aiv config set-agent-provider business --clear
 
 Valid agent roles: `business`, `architecture`, `security`, `context`.
 
-The `context` role is used by `aiv context generate`. All other roles map to the review agents.
-
 ---
 
 ### Fallback chain
@@ -675,11 +761,12 @@ After every review in an interactive terminal, aiv asks:
 ? What would you like to do with this PR?
 ❯ ✔  Approve PR
   ⚑  Request Changes
+  💬  Post as PR comment
   ────────────────────────────────────────
   ↩  Skip
 ```
 
-- **Approve** — submits an `APPROVE` review to GitHub. aiv then asks if you want to merge:
+- **Approve** — submits an `APPROVE` review to GitHub, then asks if you want to merge:
 
   ```
   ? Merge this PR now? (y/N)
@@ -693,8 +780,20 @@ After every review in an interactive terminal, aiv asks:
   After approving (with or without merge), `context.md` and `tree.json` are refreshed automatically.
 
 - **Request Changes** — submits a `REQUEST_CHANGES` review to GitHub.
+- **Post as PR comment** — publishes the full report as a formatted GitHub comment. The comment includes severity-rated findings, suggestions, and agent summaries. It also embeds the analysis data so aiv can detect it on future runs.
 - **Skip** — does nothing, exits cleanly.
 
+### Analysis cache
+
+When you run `aiv review` on a PR that already has an aiv comment, aiv detects the previous analysis and asks:
+
+```
+  Found a previous aiv analysis on this PR.
+? Use cached analysis? (Y/n)
+```
+
+Choosing yes skips the AI agents entirely and uses the stored result — no API calls, instant output. Choose no to run a fresh analysis (useful after new commits are pushed).
+
 ---
 
 ## Multi-language
@@ -728,19 +827,14 @@ AIV_LANG=es aiv prs      # per-session override
 | `AIV_LANG` | No | Override display language (`en` or `es`) |
 | `LANG` | No | System locale (auto-detected by aiv) |
 
-For custom providers, the env var name is whatever you passed to `--api-key-env`:
-
-```bash
-export KIMI_API_KEY=sk-...
-aiv config add-provider kimi --api-key-env KIMI_API_KEY ...
-```
+For custom providers, the env var name is whatever you passed to `--api-key-env`.
 
 ### GitHub token permissions
 
 | Scope | Required for |
 |-------|-------------|
 | `repo` (private repos) or `public_repo` | Reading PRs and diffs |
-| `pull_requests: write` (fine-grained PAT) | Submitting reviews and merging |
+| `pull_requests: write` (fine-grained PAT) | Submitting reviews, posting comments, merging |
 
 ---
 
@@ -758,14 +852,18 @@ cd your-repo && aiv init
 
 ### `Missing env var: GITHUB_TOKEN (account: default)`
 
-The token env var for the active account is not set.
+The token env var for the active account is not set. Check which variable name the account expects:
 
 ```bash
-export GITHUB_TOKEN=ghp_...
-# or check which account/var is active:
 aiv config accounts
 ```
 
+Then set it (once, permanently on Windows):
+
+```powershell
+[System.Environment]::SetEnvironmentVariable("GITHUB_TOKEN", "ghp_...", "User")
+```
+
 ---
 
 ### `Missing env var: CLAUDE_API_KEY`
@@ -780,10 +878,8 @@ aiv config set-provider openai
 
 ### `Unknown provider: "xyz".`
 
-A provider name was used that isn't registered.
-
 ```bash
-aiv config list-providers     # see what's configured
+aiv config list-providers
 aiv config add-provider xyz --base-url <url> --api-key-env XYZ_API_KEY --model <model>
 ```
 
@@ -791,8 +887,6 @@ aiv config add-provider xyz --base-url <url> --api-key-env XYZ_API_KEY --model <
 
 ### `Could not detect GitHub owner/repo.`
 
-The git remote is missing or not a GitHub URL.
-
 ```bash
 aiv prs --owner myorg --repo myrepo
 # or set permanently:
@@ -801,21 +895,12 @@ aiv config set-repo myorg myrepo
 
 ---
 
-### `Account "xyz" not found.`
-
-```bash
-aiv config accounts
-aiv config add-account xyz --token-env MY_TOKEN
-```
-
----
-
 ### `Failed to fetch PR: ...`
 
-- Token lacks `repo` scope — regenerate
-- PR number doesn't exist
-- GitHub rate limit — wait or switch token
-- Wrong owner/repo — check with `aiv config show`
+- Token lacks `repo` scope — regenerate with the correct scopes
+- PR number doesn't exist in this repo
+- GitHub rate limit — wait or switch to a different account
+- Wrong owner/repo — verify with `aiv config show`
 
 ---
 
@@ -823,10 +908,9 @@ aiv config add-account xyz --token-env MY_TOKEN
 
 - API key invalid or expired
 - Model quota exceeded — configure a [fallback chain](#fallback-chain)
-- Diff too large — reduce `max_tokens`:
+- Diff too large — reduce `max_tokens` in `.aiv/config.yml`:
 
 ```yaml
-# .aiv/config.yml
 review:
   max_tokens: 10000
 ```
@@ -843,26 +927,38 @@ Right after `aiv init`, run:
 aiv context generate
 ```
 
-This gives you a ready-to-edit `context.md` and `rules.yml` based on what the AI infers from your project. Tune what it gets wrong rather than writing from scratch.
+This produces a `context.md` and `rules.yml` based on what the AI infers from your project structure. Tune what it gets wrong rather than writing from scratch.
 
-### Keep rules.yml current
+### Write specific rules
 
-Add a rule whenever your team agrees on a pattern reviews should catch:
+Generic rules produce generic findings. The more specific `rules.yml` is, the more precise the business agent becomes:
 
 ```yaml
 business_rules:
   orders:
-    required_calls: [validateInventory]
-    forbidden_patterns: [skipFraudCheck]
+    required_calls: [validateInventory, reserveStock]
+    forbidden_patterns: [skipFraudCheck, directInventoryWrite]
+```
+
+### Check your own branch before opening a PR
+
+```bash
+aiv check qa       # or whatever branch you're merging into
 ```
 
+Running `aiv check` before opening a PR catches issues that would otherwise land in the reviewer's lap. If the report shows problems, save a checklist to `.aiv/checklist.md`, fix, and run `aiv check` again. Once clean, aiv detects whether the branch needs a push and handles it — you go from analysis to open PR in one step.
+
+### Post the report as a PR comment
+
+After reviewing, choose **Post as PR comment** to make the findings visible to the whole team directly in GitHub. The comment is also used as a cache — the next time anyone runs `aiv review` on the same PR, aiv detects it and offers to skip the AI calls.
+
 ### Refresh context after structural changes
 
 ```bash
 aiv context refresh
 ```
 
-Run after merging large refactors, adding modules, or changing the project layout.
+Run after merging large refactors, adding new modules, or reorganizing the project layout.
 
 ### Use a fallback chain for reliability
 
@@ -872,20 +968,20 @@ aiv config set-fallback openai gemini
 
 If your primary provider is rate-limited mid-review, aiv switches automatically without losing the run.
 
-### Match model to task with per-agent assignment
+### Match model to task
 
-Use a fast/cheap model for straightforward agents and a powerful one for the critical ones:
+Use a fast/cheap model for straightforward agents and a stronger one for the most critical:
 
 ```bash
 aiv config set-agent-provider business    claude/claude-haiku-4-5
 aiv config set-agent-provider architecture claude/claude-haiku-4-5
-aiv config set-agent-provider security    claude/claude-sonnet-4-6   # strongest model here
+aiv config set-agent-provider security    claude/claude-sonnet-4-6
 ```
 
 ### Use `--agent` to narrow focus
 
 ```bash
-aiv review 101 --agent security           # dependency bump
+aiv review 101 --agent security           # dependency bump — only security matters
 aiv review 202 --agent business architecture  # domain change
 ```
 
@@ -893,15 +989,14 @@ Fewer agents = faster, cheaper, more focused output.
 
 ### Commit `.aiv/` to the repository
 
-Committing `config.yml`, `rules.yml`, and `context.md` means every team member gets identical review behavior with no setup. Only exclude `tree.json`:
+Committing `config.yml`, `rules.yml`, and `context.md` means every team member gets identical review behavior with no local setup. `aiv init` automatically gitignores only the files that shouldn't be shared:
 
 ```
-# .gitignore
-.aiv/tree.json
+# added automatically by aiv init
+.aiv/tree.json       # auto-generated snapshot — large, noise in diffs
+.aiv/checklist.md    # personal pre-PR draft — not team-relevant
 ```
 
-`aiv init` adds this automatically.
-
 ### CI integration with `--json`
 
 ```bash
@@ -918,7 +1013,7 @@ fi
 - Not a replacement for static analysis (ESLint, SonarQube)
 - Not a style checker
 
-Its value is **semantic understanding**: catching business rule violations, architectural drift, and security risks that automated tools miss because they require project context to understand.
+Its value is **semantic understanding**: catching business rule violations, architectural drift, and security risks that automated tools miss because they don't know your project's context, rules, or intent.
 
 ---
 
@@ -928,9 +1023,9 @@ Its value is **semantic understanding**: catching business rule violations, arch
 src/
   agents/          — business, architecture, security reviewers
   cli/
-    commands/      — init, prs, review, config, context, agents
+    commands/      — init, prs, review, check, config, context, agents
     banner.ts      — ASCII welcome banner
-    renderer.ts    — review result pretty-printer
+    renderer.ts    — terminal renderer + GitHub comment builder
     selector.ts    — interactive PR/action picker (inquirer)
   config/          — two-level config load/save/merge
   context/
@@ -938,7 +1033,7 @@ src/
     generator.ts   — AI-powered context + rules generation
     manager.ts     — context reader + refreshContextFiles helper
     tree.ts        — file tree scanner
-  git/             — GitHub REST client + remote detection
+  git/             — GitHub REST client, remote detection, local diff builder
   i18n/            — EN/ES translations (all user-facing strings)
   orchestrator/    — runs agents in parallel, aggregates results
   providers/