@mrkaran/hodor 0.4.1 → 0.6.1

package/README.md

@@ -2,100 +2,166 @@
 
 # Hodor
 
-> Agentic code reviewer for GitHub PRs, GitLab MRs, and local diffs. Powered by the [pi-coding-agent](https://github.com/badlogic/pi-mono) SDK.
+> Agentic code reviewer for GitHub PRs, GitLab MRs, Gitea/Forgejo PRs, and local diffs. Powered by the [pi-coding-agent](https://github.com/badlogic/pi-mono) SDK.
 
 Hodor runs as a stateful agent with tools (`bash`, `grep`, `read`, `git diff`) to autonomously analyze code changes, find bugs, and post structured reviews.
 
 ## Install
 
 ```bash
-# npx (zero install, always latest)
+# Just run it (zero install, always latest)
 npx @mrkaran/hodor <PR_URL>
 
-# Global install
+# Or install globally
 npm install -g @mrkaran/hodor
+```
+
+Docker images are also available at `ghcr.io/mr-karan/hodor:latest` for CI environments.
 
-# Docker
-docker pull ghcr.io/mr-karan/hodor:latest
+## Setup
 
-# From source
-git clone https://github.com/mr-karan/hodor && cd hodor
-bun install && bun run build
+```bash
+# Set an API key for your LLM provider
+export ANTHROPIC_API_KEY=sk-...     # Anthropic (default)
+export OPENAI_API_KEY=sk-...        # OpenAI
+export OPENROUTER_API_KEY=sk-or-... # OpenRouter (e.g., Kimi K2.6)
+export AWS_PROFILE=default          # AWS Bedrock (no API key needed)
+
+# For posting reviews as comments
+gh auth login                     # GitHub
+glab auth login                   # GitLab
+
+# For Gitea/Forgejo private repos or posting comments
+export GITEA_TOKEN=your-token     # or FORGEJO_TOKEN
 ```
 
 ## Usage
 
 ```bash
 # Review a GitHub PR
-hodor https://github.com/owner/repo/pull/123
+npx @mrkaran/hodor https://github.com/owner/repo/pull/123
 
 # Review a GitLab MR (including self-hosted)
-hodor https://gitlab.example.com/org/project/-/merge_requests/42
+npx @mrkaran/hodor https://gitlab.example.com/org/project/-/merge_requests/42
 
-# Post the review as a comment
-hodor <PR_URL> --post
+# Review a Gitea or Forgejo PR
+npx @mrkaran/hodor https://git.example.com/owner/repo/pulls/123
 
-# Review local changes (no PR URL needed)
-hodor --local                              # diff against origin/main
-hodor --local --diff-against HEAD~1        # diff against specific ref
-hodor --local --diff-against feature-branch
+# Post the review as a PR/MR comment
+npx @mrkaran/hodor <PR_URL> --post
 
 # Use a different model
-hodor <PR_URL> --model openai/gpt-5
-hodor <PR_URL> --model bedrock/converse/anthropic.claude-sonnet-4-5-v2
+npx @mrkaran/hodor <PR_URL> --model openai/gpt-5
+npx @mrkaran/hodor <PR_URL> --model bedrock/converse/anthropic.claude-sonnet-4-5-v2
 
 # Extended reasoning for complex PRs
-hodor <PR_URL> --reasoning-effort high
-hodor <PR_URL> --ultrathink
+npx @mrkaran/hodor <PR_URL> --reasoning-effort high
 
 # Custom review instructions
-hodor <PR_URL> --prompt "Focus on SQL injection and auth bypasses"
-hodor <PR_URL> --prompt-file .hodor/security-review.md
+npx @mrkaran/hodor <PR_URL> --prompt "Focus on SQL injection and auth bypasses"
 
 # Verbose mode (watch the agent think)
-hodor <PR_URL> -v
+npx @mrkaran/hodor <PR_URL> -v
 ```
 
-**Docker:**
+> If you installed globally with `npm install -g`, replace `npx @mrkaran/hodor` with `hodor`.
+
+## Local Mode
+
+Review local git changes without a PR URL. Useful for pre-push reviews, Bitbucket PRs, or any git repo.
+
 ```bash
-docker run --rm \
-  -e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY \
-  -e GITHUB_TOKEN=$GITHUB_TOKEN \
-  ghcr.io/mr-karan/hodor:latest \
-  https://github.com/owner/repo/pull/123 --post
+# Review uncommitted changes against origin/main (default)
+npx @mrkaran/hodor --local
+
+# Review against a specific branch or ref
+npx @mrkaran/hodor --local --diff-against develop
+npx @mrkaran/hodor --local --diff-against HEAD~3
+
+# Review a feature branch against main
+git checkout feature-branch
+npx @mrkaran/hodor --local --diff-against origin/main
+
+# Use a specific workspace directory
+npx @mrkaran/hodor --local --workspace /path/to/repo
+
+# Combine with other flags
+npx @mrkaran/hodor --local --diff-against origin/main --model openai/gpt-5 -v
 ```
 
-## Configuration
+Local mode:
+- Includes **uncommitted changes** (staged + unstaged), not just commits
+- Auto-resolves to the **git repo root** (works from subdirectories)
+- Skips PR metadata fetching and workspace cloning
+- `--post` is disabled (no remote to post to)
 
-### CLI Flags
+## CLI Flags
 
 | Flag | Default | Description |
 |------|---------|-------------|
-| `--model` | `anthropic/claude-sonnet-4-5` | LLM model (Anthropic, OpenAI, or Bedrock) |
+| `--model` | `anthropic/claude-sonnet-4-5-20250929` | LLM model as `provider/model-id`. Recommended: Anthropic, OpenAI, Bedrock, OpenRouter. Other pi-ai providers (e.g., Mistral, Gemini, xAI, Groq) are best-effort. See [docs/MODELS.md](./docs/MODELS.md). |
 | `--reasoning-effort` | – | Extended thinking: `low`, `medium`, `high` |
 | `--ultrathink` | Off | Maximum reasoning effort |
-| `--local` | Off | Review local changes (no PR URL required) |
-| `--diff-against` | `origin/main` | Git ref to diff against in local mode |
-| `--post` | Off | Post review comment to GitHub/GitLab |
+| `--local` | Off | Review local git changes (no PR URL required) |
+| `--diff-against` | `origin/main` | Git ref to diff against in `--local` mode |
+| `--post` | Off | Post review as a comment on the PR/MR |
+| `--review-style` | `hybrid` | GitLab posting style: `summary`, `inline`, or `hybrid` |
+| `--code-quality` | – | Write a CodeClimate JSON artifact for GitLab code quality reports |
+| `--commit-status` | Off | Post a pass/fail commit status to the GitLab MR head SHA |
 | `--prompt` | – | Append custom instructions to the review prompt |
-| `--prompt-file` | – | Replace the review prompt entirely |
-| `--workspace` | Temp dir | Workspace directory (re-use for faster multi-PR reviews) |
+| `--prompt-file` | – | Use a custom prompt file |
+| `--workspace` | Temp dir | Workspace directory (reuse for faster multi-PR reviews) |
 | `--bedrock-tags` | – | JSON cost allocation tags for AWS Bedrock |
-| `--prometheus-push` | – | Push metrics to a Prometheus Pushgateway URL |
+| `--prometheus-push` | – | Push review metrics to a Prometheus Pushgateway or VictoriaMetrics import endpoint |
 | `-v, --verbose` | Off | Stream agent reasoning and tool calls |
 
-### Environment Variables
+## Environment Variables
 
 | Variable | Purpose |
 |----------|---------|
 | `ANTHROPIC_API_KEY` | Claude API key |
 | `OPENAI_API_KEY` | OpenAI API key |
-| `LLM_API_KEY` | Generic fallback (used when provider-specific key is not set) |
-| `GITHUB_TOKEN` / `GITLAB_TOKEN` | Post comments to PRs/MRs (only with `--post`) |
+| `OPENROUTER_API_KEY` | OpenRouter API key (for `openrouter/...` models, e.g. `openrouter/moonshotai/kimi-k2.6`) |
+| Provider-specific keys | For best-effort pi-ai providers, use the env var pi-ai expects (e.g. `MISTRAL_API_KEY`, `GEMINI_API_KEY`, `XAI_API_KEY`, `GROQ_API_KEY`) |
+| `LLM_API_KEY` | Generic fallback (when provider-specific key is not set) |
+| `GITHUB_TOKEN` / `GITLAB_TOKEN` | Post comments to GitHub PRs / GitLab MRs (with `--post`) |
+| `GITEA_TOKEN` / `FORGEJO_TOKEN` | Read private repos and post comments on Gitea/Forgejo PRs |
+| `GITEA_HOST` / `FORGEJO_HOST` | Hostname for Gitea/Forgejo when not inferable from a full PR URL |
 | `AWS_PROFILE` or `AWS_ACCESS_KEY_ID` | AWS Bedrock auth (no API key needed) |
 
+See [docs/MODELS.md](./docs/MODELS.md) for the full model/provider matrix and [docs/OPENROUTER.md](./docs/OPENROUTER.md) for an end-to-end Kimi K2.6 example.
+
+## Gitea / Forgejo
+
+Hodor supports Gitea and Forgejo pull request URLs in this format:
+
+```bash
+npx @mrkaran/hodor https://git.example.com/owner/repo/pulls/123
+```
+
+For public repositories, metadata fetching may work without a token. Set `GITEA_TOKEN` or `FORGEJO_TOKEN` for private repositories, higher API limits, and `--post`:
+
+```bash
+export GITEA_TOKEN=your-token
+npx @mrkaran/hodor https://git.example.com/owner/repo/pulls/123 --post
+```
+
+Fork PRs are checked out from the PR source repository when Gitea exposes the source clone URL. If the source branch or fork has been deleted, checkout will fail with a workspace error.
+
 ## CI/CD
 
+### Metrics in CI
+
+Hodor can push per-review metrics at the end of a CI run to either a Prometheus Pushgateway base URL or a VictoriaMetrics Prometheus import endpoint (`/api/v1/import/prometheus`):
+
+```bash
+hodor "$MR_OR_PR_URL" --prometheus-push "$METRICS_PUSH_URL"
+```
+
+In CI, set `METRICS_PUSH_URL` as a secret/variable and add `--prometheus-push "$METRICS_PUSH_URL"` to the Hodor command. Metrics are best-effort: push failures are logged as warnings and do not fail the review job.
+
+Each metric is labeled with `platform`, `model`, `verdict`, and for PR/MR URLs also `project` (`owner/repo`) and `mr_iid`/PR number. Exported metrics include token usage, cache read/write tokens, cache hit ratio, cost, turns, tool calls, duration, and findings by priority (`P0`–`P3`). A generic Grafana dashboard is available in [`docs/grafana/`](./docs/grafana/).
+
 ### GitHub Actions
 
 ```yaml
@@ -113,42 +179,66 @@ jobs:
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+          METRICS_PUSH_URL: ${{ secrets.METRICS_PUSH_URL }} # optional
         run: |
-          hodor "https://github.com/${{ github.repository }}/pull/${{ github.event.pull_request.number }}" --post
+          EXTRA_ARGS=""
+          if [ -n "${METRICS_PUSH_URL:-}" ]; then EXTRA_ARGS="--prometheus-push $METRICS_PUSH_URL"; fi
+          bun run /app/dist/cli.js "https://github.com/${{ github.repository }}/pull/${{ github.event.pull_request.number }}" --post $EXTRA_ARGS
 ```
 
 ### GitLab CI
 
 ```yaml
-include:
-  - project: 'commons/gitlab-templates'
-    ref: master
-    file: '/hodor/.gitlab-ci-template.yml'
+# .gitlab-ci.yml
+workflow:
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
 
 hodor-review:
-  extends: .hodor-review
+  stage: test
+  image:
+    name: ghcr.io/mr-karan/hodor:latest
+    entrypoint: [""]
+  variables:
+    HODOR_MODEL: "anthropic/claude-sonnet-4-5-20250929"
+  before_script:
+    - glab auth login --hostname $CI_SERVER_HOST --token $GITLAB_TOKEN
+  script:
+    - MR_URL="${CI_PROJECT_URL}/-/merge_requests/${CI_MERGE_REQUEST_IID}"
+    - |
+      EXTRA_ARGS=""
+      if [ -n "${METRICS_PUSH_URL:-}" ]; then EXTRA_ARGS="--prometheus-push $METRICS_PUSH_URL"; fi
+      bun run /app/dist/cli.js "$MR_URL" --model "$HODOR_MODEL" --post --code-quality gl-code-quality-report.json --commit-status $EXTRA_ARGS
+  artifacts:
+    reports:
+      codequality: gl-code-quality-report.json
+    when: always
+  allow_failure: true
+  timeout: 15m
 ```
 
+This posts inline comments on the diff, a summary note, a pass/fail commit status, and a code quality report visible in the MR widget.
+
 See [AUTOMATED_REVIEWS.md](./docs/AUTOMATED_REVIEWS.md) for advanced workflows.
 
 ## Token Optimization
 
 Hodor automatically optimizes token usage:
 
-- **Diff embedding**: For PRs under 200KB, the diff is embedded directly in the prompt, cutting turns from ~60 to ~5.
-- **Incremental reviews**: On re-runs, only reviews changes since the last hodor comment (detected via SHA markers).
-- **Compaction**: SDK auto-summarizes older turns when context grows too large.
+- **Diff embedding**: For PRs under 200KB, the diff is embedded directly in the prompt, cutting agent turns from ~60 to ~5.
+- **Incremental reviews**: On re-runs, only reviews changes since the last hodor comment (detected via SHA markers in posted comments).
+- **Compaction**: SDK auto-summarizes older conversation turns when context grows too large.
 
 ## Skills
 
-Hodor discovers repository-specific review guidelines from `.pi/skills/` or `.hodor/skills/`. Create a skill file to enforce conventions:
+Hodor discovers repository-specific review guidelines from `.agents/skills/`, the cross-client Agent Skills convention:
 
 ```bash
-mkdir -p .hodor/skills/review-guidelines
+mkdir -p .agents/skills/review-guidelines
 ```
 
 ```markdown
-# .hodor/skills/review-guidelines/SKILL.md
+# .agents/skills/review-guidelines/SKILL.md
 ---
 name: review-guidelines
 description: Security and performance review checklist.
@@ -170,6 +260,40 @@ bun run test         # Run tests
 bun run dev -- <url> # Run from source
 ```
 
+---
+
+## Architecture
+
+Hodor is written in TypeScript and runs on [Bun](https://bun.sh). Key components:
+
+| Module | Purpose |
+|--------|---------|
+| `src/cli.ts` | Commander.js CLI entry point |
+| `src/agent.ts` | Core review orchestration, URL parsing, comment posting |
+| `src/workspace.ts` | CI detection, repo cloning, branch checkout |
+| `src/prompt.ts` | Prompt template building and interpolation |
+| `src/model.ts` | Model string parsing, API key resolution |
+| `src/gitlab.ts` | GitLab API via `glab` CLI (comments, inline notes, draft notes, commit status) |
+| `src/github.ts` | GitHub API via `gh` CLI |
+| `src/render.ts` | JSON review output → markdown rendering |
+| `src/codequality.ts` | CodeClimate JSON artifact for GitLab code quality widget |
+| `src/metrics.ts` | Token usage and cost formatting |
+| `templates/` | Review prompt template (JSON schema) |
+
+The agent runtime is provided by [`@mariozechner/pi-coding-agent`](https://github.com/badlogic/pi-mono) with [`@mariozechner/pi-ai`](https://github.com/badlogic/pi-mono) for LLM access. The agent session gets read-only tools (bash, read, grep, find, ls) and a review prompt, then autonomously analyzes the PR.
+
+---
+
+## Learn More
+
+### Hodor Documentation
+- **[SKILLS.md](./docs/SKILLS.md)** - Creating repository-specific review guidelines
+- **[AUTOMATED_REVIEWS.md](./docs/AUTOMATED_REVIEWS.md)** - Advanced CI/CD workflows
+
+### Contributing
+Found a bug? Want to add a feature? Open an issue at https://github.com/mr-karan/hodor/issues.
+
+---
 ## License
 
 MIT

package/dist/chunk-AMUK6GDX.js

@@ -0,0 +1,23 @@
+// src/utils/path.ts
+function relativizeWorkspacePath(absolutePath, workspacePrefix) {
+  let filePath = absolutePath;
+  const prefix = workspacePrefix ?? process.env.CI_PROJECT_DIR;
+  if (prefix) {
+    const trimmed = prefix.replace(/\/+$/, "");
+    if (filePath.startsWith(`${trimmed}/`)) {
+      return filePath.slice(trimmed.length + 1);
+    }
+  }
+  const buildsMatch = filePath.match(/\/builds\/[^/]+\/[^/]+\/(.+)/);
+  if (buildsMatch) return buildsMatch[1];
+  if (filePath.includes("/workspace/")) {
+    return filePath.slice(filePath.indexOf("/workspace/") + "/workspace/".length);
+  }
+  const stripped = filePath.replace(/^.*\/hodor-review-[^/]+\//, "");
+  return stripped !== filePath ? stripped : filePath;
+}
+
+export {
+  relativizeWorkspacePath
+};
+//# sourceMappingURL=chunk-AMUK6GDX.js.map

package/dist/chunk-AMUK6GDX.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/utils/path.ts"],"sourcesContent":["/**\n * Strip workspace/CI prefixes from an absolute path so it becomes repo-relative.\n *\n * Used both for inline-comment paths posted to GitLab (must match the diff path)\n * and for the CodeClimate code quality artifact (GitLab compares against repo\n * paths, not the temp-dir absolute paths Hodor sees during a review).\n *\n * Honors `CI_PROJECT_DIR` first when set (GitLab CI sets it to the checkout root).\n * Otherwise, falls through generic patterns: GitLab `/builds/<group>/<project>/...`,\n * a `/workspace/...` segment, and Hodor's own `/tmp/hodor-review-<id>/...` temp dirs.\n */\nexport function relativizeWorkspacePath(absolutePath: string, workspacePrefix?: string): string {\n  let filePath = absolutePath;\n\n  const prefix = workspacePrefix ?? process.env.CI_PROJECT_DIR;\n  if (prefix) {\n    const trimmed = prefix.replace(/\\/+$/, \"\");\n    if (filePath.startsWith(`${trimmed}/`)) {\n      return filePath.slice(trimmed.length + 1);\n    }\n  }\n\n  const buildsMatch = filePath.match(/\\/builds\\/[^/]+\\/[^/]+\\/(.+)/);\n  if (buildsMatch) return buildsMatch[1];\n\n  if (filePath.includes(\"/workspace/\")) {\n    return filePath.slice(filePath.indexOf(\"/workspace/\") + \"/workspace/\".length);\n  }\n\n  const stripped = filePath.replace(/^.*\\/hodor-review-[^/]+\\//, \"\");\n  return stripped !== filePath ? stripped : filePath;\n}\n"],"mappings":";AAWO,SAAS,wBAAwB,cAAsB,iBAAkC;AAC9F,MAAI,WAAW;AAEf,QAAM,SAAS,mBAAmB,QAAQ,IAAI;AAC9C,MAAI,QAAQ;AACV,UAAM,UAAU,OAAO,QAAQ,QAAQ,EAAE;AACzC,QAAI,SAAS,WAAW,GAAG,OAAO,GAAG,GAAG;AACtC,aAAO,SAAS,MAAM,QAAQ,SAAS,CAAC;AAAA,IAC1C;AAAA,EACF;AAEA,QAAM,cAAc,SAAS,MAAM,8BAA8B;AACjE,MAAI,YAAa,QAAO,YAAY,CAAC;AAErC,MAAI,SAAS,SAAS,aAAa,GAAG;AACpC,WAAO,SAAS,MAAM,SAAS,QAAQ,aAAa,IAAI,cAAc,MAAM;AAAA,EAC9E;AAEA,QAAM,WAAW,SAAS,QAAQ,6BAA6B,EAAE;AACjE,SAAO,aAAa,WAAW,WAAW;AAC5C;","names":[]}