bitbucket-gemini-action 1.0.0

package/.claude/settings.local.json

@@ -0,0 +1,8 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(bun run typecheck:*)",
+      "Bash(bun install:*)"
+    ]
+  }
+}

package/.prettierrc

@@ -0,0 +1,8 @@
+{
+  "semi": true,
+  "singleQuote": false,
+  "tabWidth": 2,
+  "trailingComma": "es5",
+  "printWidth": 80,
+  "useTabs": false
+}

package/CLAUDE.md

@@ -0,0 +1,150 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code when working with this repository.
+
+## Project Overview
+
+This is a Bitbucket Pipeline action that enables AI-powered code review using Google Gemini. The action responds to @gemini mentions in PR comments and can perform automated code reviews.
+
+## Development Tools
+
+- Runtime: Bun 1.2+
+- TypeScript with strict configuration
+- Target: Node.js 20+
+
+## Common Development Tasks
+
+```bash
+# Install dependencies
+bun install
+
+# Type checking
+bun run typecheck
+
+# Format code
+bun run format
+bun run format:check
+
+# Run tests
+bun test
+
+# Build
+bun run build
+```
+
+## Architecture Overview
+
+The action operates in two phases:
+
+### Phase 1: Prepare (`src/entrypoints/prepare.ts`)
+
+1. Parse Bitbucket Pipeline context and environment
+2. Validate trigger conditions (@gemini mention or explicit prompt)
+3. Validate actor permissions
+4. Create tracking comment for progress visibility
+5. Output context for execution phase
+
+### Phase 2: Execute (`src/entrypoints/execute.ts`)
+
+1. Load context from prepare phase
+2. Fetch PR data (diff, comments, commits)
+3. Build prompt with PR context
+4. Call Gemini API with function calling
+5. Process tool calls (create comments, inline feedback)
+6. Update tracking comment with results
+
+## Key Components
+
+### Bitbucket Integration (`src/bitbucket/`)
+
+- **api/client.ts**: REST API client for Bitbucket Cloud v2.0
+- **context.ts**: Parse pipeline environment variables
+- **data/fetcher.ts**: Fetch PR data with timestamp filtering
+- **data/formatter.ts**: Format data for prompts
+- **validation/**: Permission and trigger validation
+- **operations/**: Comment creation and updates
+
+### Gemini Integration (`src/gemini/`)
+
+- **client.ts**: Gemini API wrapper using @google/generative-ai
+- **prompts.ts**: System prompts and prompt builders
+- **tools.ts**: Function declarations for tool calling
+
+### Mode System (`src/modes/`)
+
+- **tag/**: Interactive mode triggered by @gemini mentions
+- **agent/**: Automated mode with explicit prompts
+- **registry.ts**: Mode detection and selection
+
+## Environment Variables
+
+Required:
+- `GEMINI_API_KEY` or `GOOGLE_API_KEY`: Gemini API key
+- `BITBUCKET_ACCESS_TOKEN` or `BITBUCKET_USERNAME`/`BITBUCKET_APP_PASSWORD`: Bitbucket credentials
+
+Pipeline-provided:
+- `BITBUCKET_WORKSPACE`: Workspace slug
+- `BITBUCKET_REPO_SLUG`: Repository slug
+- `BITBUCKET_COMMIT`: Current commit hash
+- `BITBUCKET_PR_ID`: PR number (if PR context)
+
+Optional:
+- `TRIGGER_PHRASE`: Custom trigger (default: "@gemini")
+- `GEMINI_MODEL`: Model to use (default: "gemini-2.0-flash")
+- `MODE`: Force mode ("tag" or "agent")
+- `PROMPT`: Explicit prompt for agent mode
+
+## Code Conventions
+
+- Use Bun-specific TypeScript with `moduleResolution: "bundler"`
+- Strict TypeScript with `noUnusedLocals` and `noUnusedParameters`
+- Explicit error handling with detailed messages
+- Use Zod for runtime validation
+- Implement retry logic for API operations
+
+## Security Considerations
+
+1. **Timestamp Filtering**: Filter out comments modified after trigger time to prevent injection
+2. **Bot Detection**: Check if comment author is the bot itself to prevent loops
+3. **Permission Validation**: Verify write permissions before taking action
+4. **Content Sanitization**: Remove potential prompt injection patterns
+
+## Testing
+
+Tests use Bun's built-in test runner:
+
+```bash
+# Run all tests
+bun test
+
+# Run specific test file
+bun test src/bitbucket/api/client.test.ts
+
+# Watch mode
+bun test --watch
+```
+
+## Project Structure
+
+```
+src/
+├── bitbucket/           # Bitbucket API integration
+│   ├── api/             # REST client
+│   ├── data/            # Fetching & formatting
+│   ├── operations/      # PR/comment operations
+│   └── validation/      # Permissions & triggers
+├── gemini/              # Gemini API integration
+│   ├── client.ts        # API wrapper
+│   ├── prompts.ts       # Prompt templates
+│   └── tools.ts         # Function calling
+├── modes/               # Execution modes
+│   ├── tag/             # @mention mode
+│   ├── agent/           # Automation mode
+│   └── registry.ts      # Mode detection
+├── entrypoints/         # Pipeline entry points
+│   ├── prepare.ts       # Phase 1
+│   └── execute.ts       # Phase 2
+└── utils/               # Shared utilities
+    ├── env.ts           # Environment config
+    └── retry.ts         # Retry logic
+```

package/README.md

@@ -0,0 +1,375 @@
+# Bitbucket Gemini Action
+
+AI-powered code review for Bitbucket using Google Gemini. Automatically review pull requests, respond to mentions, and provide intelligent code feedback.
+
+## Features
+
+- 🤖 **AI Code Review**: Automatically analyze PRs for bugs, security issues, and code quality
+- 💬 **@gemini Mentions**: Respond to questions and requests in PR comments
+- 🔧 **Inline Comments**: Post targeted feedback on specific lines of code
+- 📊 **Progress Tracking**: Visual tracking comments show review progress
+- 🔄 **Two Modes**: Tag mode (interactive) and Agent mode (automated)
+
+## Quick Start
+
+### 1. Set up Repository Variables
+
+Go to **Repository settings > Repository variables** and add:
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `GEMINI_API_KEY` | Yes | Your Google Gemini API key |
+| `BITBUCKET_ACCESS_TOKEN` | Yes* | Bitbucket access token with PR permissions |
+| `BITBUCKET_USERNAME` | Yes* | Username for basic auth |
+| `BITBUCKET_APP_PASSWORD` | Yes* | App password for basic auth |
+
+*Either `BITBUCKET_ACCESS_TOKEN` OR both `BITBUCKET_USERNAME` and `BITBUCKET_APP_PASSWORD` are required.
+
+### 2. Add Pipeline Configuration
+
+Create or update your `bitbucket-pipelines.yml`:
+
+```yaml
+image: node:20
+
+pipelines:
+  pull-requests:
+    '**':
+      - step:
+          name: AI Code Review
+          script:
+            - curl -fsSL https://bun.sh/install | bash
+            - export PATH="$HOME/.bun/bin:$PATH"
+            - npx bitbucket-gemini-action
+```
+
+### 3. Use the Action
+
+**Automatic Review**: PRs are automatically reviewed when opened or updated.
+
+**Manual Trigger**: Comment `@gemini` followed by your request:
+- `@gemini review this PR`
+- `@gemini what does this function do?`
+- `@gemini check for security issues`
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `GEMINI_API_KEY` | - | Google Gemini API key |
+| `GOOGLE_API_KEY` | - | Alternative to GEMINI_API_KEY |
+| `TRIGGER_PHRASE` | `@gemini` | Phrase to trigger bot |
+| `GEMINI_MODEL` | `gemini-2.0-flash` | Gemini model to use |
+| `MODE` | auto | `tag` or `agent` |
+| `CREATE_TRACKING_COMMENT` | `true` | Show progress comment |
+| `PROMPT` | - | Custom prompt for agent mode |
+
+### Available Models
+
+- `gemini-2.0-flash` (default) - Fast and efficient
+- `gemini-2.0-flash-lite` - Faster, lower cost
+- `gemini-1.5-pro` - More capable, slower
+- `gemini-1.5-flash` - Balanced option
+
+## Review Presets
+
+리뷰 프리셋을 사용하여 리뷰 스타일과 관점을 커스터마이징할 수 있습니다.
+
+### 환경 변수
+
+| Variable | Description |
+|----------|-------------|
+| `REVIEW_PRESETS` | 쉼표로 구분된 프리셋 키 목록 (예: `junior,nextjs,security`) |
+| `CUSTOM_PROMPT` | 추가 커스텀 프롬프트 |
+
+### 사용 예시
+
+```yaml
+# 주니어 개발자 + Next.js 프로젝트
+- step:
+    script:
+      - export REVIEW_PRESETS="junior,nextjs"
+      - npx bitbucket-gemini-action
+
+# 시니어 + 아키텍처 + 보안 리뷰
+- step:
+    script:
+      - export REVIEW_PRESETS="senior,architecture,security"
+      - npx bitbucket-gemini-action
+
+# 챗봇 프로젝트 + RAG 시스템
+- step:
+    script:
+      - export REVIEW_PRESETS="chatbot,rag,typescript"
+      - npx bitbucket-gemini-action
+
+# 커스텀 프롬프트 추가
+- step:
+    script:
+      - export REVIEW_PRESETS="middle,nestjs"
+      - export CUSTOM_PROMPT="특히 DB 쿼리 최적화에 집중해주세요"
+      - npx bitbucket-gemini-action
+```
+
+### 사용 가능한 프리셋
+
+#### 경험 레벨 (Experience)
+
+| Key | Name | Description |
+|-----|------|-------------|
+| `junior` | 주니어 개발자용 | 친절하고 교육적인 리뷰, 기본 개념 설명 포함 |
+| `middle` | 미들급 개발자용 | 디자인 패턴, 트레이드오프 분석 |
+| `senior` | 시니어 개발자용 | 아키텍처 수준 피드백, 간결한 분석 |
+| `lead` | 테크 리드용 | 팀 관점, 멘토링 기회 식별 |
+
+#### 리뷰 관점 (Perspective)
+
+| Key | Name | Description |
+|-----|------|-------------|
+| `architecture` | 아키텍처/설계 | SOLID, 모듈화, 확장성 |
+| `security` | 보안 | 취약점, 인증/인가, 민감 데이터 |
+| `performance` | 성능 | 알고리즘, DB, 메모리, 비동기 |
+| `testing` | 테스트 | 커버리지, 테스트 품질, 모킹 |
+| `accessibility` | 접근성 (a11y) | 시맨틱 HTML, ARIA, 키보드 |
+| `errorHandling` | 에러 핸들링 | 예외 처리, 복구 전략 |
+| `codeStyle` | 코드 스타일 | 네이밍, 가독성, 일관성 |
+
+#### 프레임워크 (Framework)
+
+| Key | Name | Description |
+|-----|------|-------------|
+| `react` | React | Hooks, 컴포넌트 설계, 상태 관리 |
+| `nextjs` | Next.js | App Router, Server Components, Data Fetching |
+| `vue` | Vue.js | Composition API, Composables |
+| `angular` | Angular | 모듈, DI, RxJS |
+| `nestjs` | NestJS | 모듈, Guard/Pipe, DTO |
+| `express` | Express.js | 미들웨어, 라우팅, 보안 |
+| `fastify` | Fastify | 플러그인, 스키마, 훅 |
+| `springboot` | Spring Boot | 레이어, JPA, Security |
+| `django` | Django | 모델, ORM, DRF |
+| `flask` | Flask | 블루프린트, SQLAlchemy |
+
+#### 도메인 (Domain)
+
+| Key | Name | Description |
+|-----|------|-------------|
+| `frontend` | 프론트엔드 일반 | UI/UX, 상태 관리, 스타일링 |
+| `backend` | 백엔드 일반 | API 설계, DB, 인증 |
+| `fullstack` | 풀스택 | API 계약, 데이터 흐름 |
+| `mobile` | 모바일 | React Native, Flutter |
+| `devops` | DevOps/인프라 | CI/CD, IaC, K8s |
+| `database` | 데이터베이스 | 스키마, 인덱스, 쿼리 |
+
+#### 프로그래밍 언어 (Language)
+
+| Key | Name | Description |
+|-----|------|-------------|
+| `typescript` | TypeScript | 타입 시스템, 제네릭, 유틸리티 타입 |
+| `javascript` | JavaScript | ES6+, 비동기, 모듈 |
+| `python` | Python | PEP 8, Pythonic 코드 |
+| `go` | Go | 관용구, 동시성, 에러 처리 |
+| `java` | Java | 모던 Java, OOP, 동시성 |
+| `rust` | Rust | 소유권, 에러 처리, 동시성 |
+
+#### AI/ML
+
+| Key | Name | Description |
+|-----|------|-------------|
+| `chatbot` | 챗봇/대화형 AI | 대화 관리, 프롬프트, RAG |
+| `llmIntegration` | LLM API 통합 | API 클라이언트, 에러 처리, 비용 |
+| `rag` | RAG 시스템 | 문서 처리, 임베딩, 검색 |
+| `aiAgent` | AI 에이전트 | 계획-실행, 도구 사용, 안전성 |
+| `mlOps` | MLOps | 모델 관리, 파이프라인, 모니터링 |
+| `promptEngineering` | 프롬프트 엔지니어링 | 프롬프트 설계, 최적화 |
+| `vectorDB` | 벡터 데이터베이스 | 인덱스, 쿼리 최적화 |
+| `langchain` | LangChain | 체인, 에이전트, 메모리 |
+
+#### 코드 품질 (Quality)
+
+| Key | Name | Description |
+|-----|------|-------------|
+| `cleanCode` | 클린 코드 | 클린 코드 원칙 |
+| `refactoring` | 리팩토링 기회 | 코드 스멜 식별 |
+| `documentation` | 문서화 | API 문서, 주석 |
+| `maintainability` | 유지보수성 | 가독성, 모듈성, 테스트 가능성 |
+
+### 프리셋 조합 예시
+
+```yaml
+# 프론트엔드 팀
+REVIEW_PRESETS="junior,react,frontend,accessibility"
+
+# 백엔드 팀
+REVIEW_PRESETS="middle,nestjs,backend,security,performance"
+
+# AI/챗봇 팀
+REVIEW_PRESETS="senior,chatbot,rag,langchain,typescript"
+
+# 풀스택 코드 리뷰
+REVIEW_PRESETS="middle,nextjs,nestjs,fullstack"
+
+# 코드 품질 중심
+REVIEW_PRESETS="cleanCode,refactoring,maintainability,testing"
+```
+
+## Modes
+
+### Tag Mode (Interactive)
+
+Triggered by `@gemini` mentions in comments. Responds directly to user requests.
+
+```
+@gemini Can you explain what this function does?
+```
+
+### Agent Mode (Automated)
+
+Triggered by providing a `PROMPT` variable. Executes predefined tasks automatically.
+
+```yaml
+- step:
+    script:
+      - export PROMPT="Review for security vulnerabilities"
+      - npx bitbucket-gemini-action
+```
+
+## Pipeline Examples
+
+### Basic PR Review
+
+```yaml
+pipelines:
+  pull-requests:
+    '**':
+      - step:
+          name: AI Code Review
+          script:
+            - curl -fsSL https://bun.sh/install | bash
+            - export PATH="$HOME/.bun/bin:$PATH"
+            - npx bitbucket-gemini-action
+```
+
+### Custom Review Prompt
+
+```yaml
+pipelines:
+  custom:
+    security-review:
+      - step:
+          name: Security Review
+          script:
+            - curl -fsSL https://bun.sh/install | bash
+            - export PATH="$HOME/.bun/bin:$PATH"
+            - export MODE="agent"
+            - export PROMPT="Focus on security: SQL injection, XSS, authentication issues"
+            - npx bitbucket-gemini-action
+```
+
+### Scheduled Reviews
+
+```yaml
+definitions:
+  steps:
+    - step: &review
+        name: Review
+        script:
+          - npx bitbucket-gemini-action
+
+schedules:
+  - cron: "0 9 * * 1-5"
+    pipeline: custom/daily-review
+```
+
+## How It Works
+
+1. **Prepare Phase**: Parses Bitbucket context, validates triggers, creates tracking comment
+2. **Execute Phase**: Calls Gemini API, processes response, posts comments
+
+```
+┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
+│   PR Event or   │────▶│  Prepare Phase  │────▶│  Execute Phase  │
+│   @gemini Tag   │     │  - Parse context│     │  - Call Gemini  │
+│                 │     │  - Validate     │     │  - Post comments│
+└─────────────────┘     └─────────────────┘     └─────────────────┘
+```
+
+## Project Structure
+
+```
+bitbucket-gemini-action/
+├── src/
+│   ├── bitbucket/          # Bitbucket API integration
+│   │   ├── api/            # REST API client
+│   │   ├── data/           # Data fetching & formatting
+│   │   ├── operations/     # Comment operations
+│   │   └── validation/     # Permission & trigger validation
+│   ├── gemini/             # Gemini API integration
+│   │   ├── client.ts       # API client
+│   │   ├── prompts.ts      # Prompt templates
+│   │   └── tools.ts        # Function calling tools
+│   ├── modes/              # Execution modes
+│   │   ├── tag/            # @gemini mention mode
+│   │   └── agent/          # Automation mode
+│   ├── entrypoints/        # Pipeline entry points
+│   │   ├── prepare.ts      # Phase 1
+│   │   └── execute.ts      # Phase 2
+│   └── utils/              # Shared utilities
+├── examples/               # Pipeline examples
+├── bitbucket-pipelines.yml # Main pipeline config
+└── package.json
+```
+
+## Security
+
+- **Timestamp Filtering**: Comments modified after trigger time are ignored
+- **Bot Detection**: Prevents infinite loops from bot comments
+- **Permission Validation**: Verifies actor has write permissions
+- **Content Sanitization**: Removes potential prompt injection attempts
+
+## Development
+
+```bash
+# Install dependencies
+bun install
+
+# Type check
+bun run typecheck
+
+# Format code
+bun run format
+
+# Run tests
+bun test
+```
+
+## Troubleshooting
+
+### "Missing Gemini API key"
+
+Ensure `GEMINI_API_KEY` or `GOOGLE_API_KEY` is set in repository variables.
+
+### "Missing Bitbucket credentials"
+
+Set either:
+- `BITBUCKET_ACCESS_TOKEN`, or
+- Both `BITBUCKET_USERNAME` and `BITBUCKET_APP_PASSWORD`
+
+### "Comment does not contain trigger phrase"
+
+The default trigger is `@gemini`. Check if you've customized `TRIGGER_PHRASE`.
+
+### Bot not responding to comments
+
+1. Ensure the pipeline is triggered by PR events
+2. Check that credentials have PR comment permissions
+3. Verify the trigger phrase is in the comment
+
+## License
+
+MIT
+
+## Credits
+
+Inspired by [claude-code-action](https://github.com/anthropics/claude-code-action) by Anthropic.

package/bitbucket-pipelines.yml

@@ -0,0 +1,95 @@
+# Bitbucket Gemini Action Pipeline
+# AI-powered code review using Google Gemini
+
+image: node:20
+
+definitions:
+  caches:
+    bun: ~/.bun
+
+  steps:
+    - step: &gemini-review
+        name: Gemini Code Review
+        caches:
+          - bun
+        script:
+          # Install Bun
+          - curl -fsSL https://bun.sh/install | bash
+          - export BUN_INSTALL="$HOME/.bun"
+          - export PATH="$BUN_INSTALL/bin:$PATH"
+          - bun --version
+
+          # Clone the action repository (or use as a submodule)
+          - |
+            if [ ! -d ".gemini-action" ]; then
+              git clone https://github.com/your-org/bitbucket-gemini-action.git .gemini-action
+            fi
+
+          # Install dependencies
+          - cd .gemini-action && bun install && cd ..
+
+          # Run prepare phase
+          - bun run .gemini-action/src/entrypoints/prepare.ts
+
+          # Check if we should continue
+          - |
+            if [ -f ".gemini-action-output.json" ]; then
+              SHOULD_CONTINUE=$(cat .gemini-action-output.json | jq -r '.containsTrigger')
+              if [ "$SHOULD_CONTINUE" != "true" ]; then
+                echo "No trigger detected, skipping execution"
+                exit 0
+              fi
+            fi
+
+          # Run execute phase
+          - bun run .gemini-action/src/entrypoints/execute.ts
+
+pipelines:
+  pull-requests:
+    '**':
+      - step:
+          <<: *gemini-review
+          name: AI Code Review
+          condition:
+            changesets:
+              includePaths:
+                - "**/*"
+
+  custom:
+    gemini-review:
+      - variables:
+          - name: PROMPT
+            default: "Review this PR for bugs, security issues, and code quality."
+          - name: MODE
+            default: "agent"
+      - step:
+          <<: *gemini-review
+          name: Manual Gemini Review
+
+    gemini-full-review:
+      - step:
+          <<: *gemini-review
+          name: Full Code Review
+          script:
+            - curl -fsSL https://bun.sh/install | bash
+            - export BUN_INSTALL="$HOME/.bun"
+            - export PATH="$BUN_INSTALL/bin:$PATH"
+            - |
+              if [ ! -d ".gemini-action" ]; then
+                git clone https://github.com/your-org/bitbucket-gemini-action.git .gemini-action
+              fi
+            - cd .gemini-action && bun install && cd ..
+            - PROMPT="Perform a comprehensive code review focusing on: 1) Security vulnerabilities 2) Performance issues 3) Code quality 4) Best practices 5) Documentation" bun run .gemini-action/src/entrypoints/prepare.ts
+            - bun run .gemini-action/src/entrypoints/execute.ts
+
+# Environment variables required:
+# - GEMINI_API_KEY or GOOGLE_API_KEY: Your Google Gemini API key
+# - BITBUCKET_ACCESS_TOKEN: Bitbucket access token with PR comment permissions
+#   OR
+# - BITBUCKET_USERNAME and BITBUCKET_APP_PASSWORD: Basic auth credentials
+#
+# Optional variables:
+# - TRIGGER_PHRASE: Phrase to trigger review (default: "@gemini")
+# - GEMINI_MODEL: Gemini model to use (default: "gemini-2.0-flash")
+# - CREATE_TRACKING_COMMENT: Create progress comment (default: "true")
+# - MODE: Execution mode - "tag" or "agent" (default: auto-detect)