@aaronshaf/ger 0.1.0

package/DEVELOPMENT.md

@@ -0,0 +1,361 @@
+# Development Guide
+
+This document contains information for developers working on the Gerrit CLI project.
+
+## Prerequisites
+
+- **Bun 1.0+** - Primary runtime and package manager
+- **Node.js 18+** - For tooling compatibility
+- **Git** - Version control
+
+## Getting Started
+
+### Initial Setup
+```bash
+git clone https://github.com/your-org/gerrit-cli
+cd gerrit-cli
+bun install
+```
+
+### Development Commands
+```bash
+# Development
+bun run dev                 # Run CLI in development mode
+bun run dev --help          # Show CLI help
+bun run build              # Build for production
+
+# Testing
+bun test                   # Run all tests
+bun run test:coverage      # Run tests with coverage report
+bun test tests/unit/       # Run only unit tests
+bun test tests/integration/ # Run only integration tests
+
+# Code Quality
+bun run typecheck          # TypeScript type checking
+bun run lint               # Run oxlint
+bun run format             # Format code with Biome
+bun run format:check       # Check code formatting
+bun run check:all          # Run all checks (typecheck, lint, format, test)
+```
+
+## Architecture
+
+The project follows a clean, functional architecture using Effect:
+
+### Directory Structure
+```
+src/
+├── cli/              # Ink components and command definitions
+│   ├── commands/     # Individual command implementations
+│   └── index.ts      # Main CLI entry point
+├── services/         # Effect services
+│   └── config.ts     # Configuration management
+├── api/              # Gerrit REST API client
+│   └── gerrit.ts     # API service implementation
+├── db/               # SQLite caching layer
+│   ├── database.ts   # Database service
+│   └── schema.ts     # SQL schema definitions
+├── schemas/          # Effect Schema definitions
+│   └── gerrit.ts     # Type-safe data models
+├── i18n/             # Internationalization (future)
+└── utils/            # Shared utilities
+
+tests/
+├── unit/             # Unit tests
+├── integration/      # Integration tests
+├── mocks/            # MSW mock handlers
+└── setup.ts          # Test setup and configuration
+```
+
+### Key Technologies
+
+- **Effect** - Functional effect system for managing side effects
+- **Effect Schema** - Type-safe data validation and transformation
+- **Ink** - React for CLIs, providing interactive terminal UI
+- **Bun SQLite** - Built-in SQLite support for caching
+- **MSW** - Mock Service Worker for API testing
+- **Commander.js** - CLI argument parsing
+
+### Design Principles
+
+1. **Functional Programming** - Use Effect for all side effects
+2. **Type Safety** - Leverage TypeScript with strict settings
+3. **Local-First** - Cache everything, work offline when possible
+4. **Error Handling** - Comprehensive error types and handling
+5. **Testing** - High test coverage with shared schemas
+
+## Code Quality Standards
+
+### TypeScript Configuration
+- `isolatedDeclarations: true` - Explicit type exports
+- `noImplicitAny: true` - No implicit any types
+- `strictNullChecks: true` - Strict null checking
+- Only `.ts` files allowed (no `.js/.jsx/.tsx`)
+
+### Linting & Formatting
+- **oxlint** - Fast, strict linting
+- **Biome** - Consistent code formatting
+- **ast-grep** - Pattern-based code rules
+
+### File Size Limits
+- **Warning** at 500 lines
+- **Error** at 700 lines
+- Enforced in pre-commit hooks
+
+### Banned Patterns
+- `as` type casting (except `as const` and `as unknown`)
+- `--no-verify` flag usage
+- Implicit any types
+- console.log in production code
+
+## Testing Strategy
+
+### Test Types
+1. **Unit Tests** - Pure functions, schemas, utilities
+2. **Integration Tests** - API clients with MSW mocks
+3. **Component Tests** - CLI command behavior
+
+### Shared Schemas
+Test mocks use the same Effect Schemas as production code, ensuring type safety and consistency.
+
+### Coverage Requirements
+- **Minimum 80%** line coverage
+- **Minimum 80%** function coverage
+- **Minimum 80%** branch coverage
+- **Minimum 80%** statement coverage
+
+### Running Tests
+```bash
+# All tests
+bun test
+
+# Watch mode
+bun test --watch
+
+# Specific test file
+bun test tests/unit/schemas/gerrit.test.ts
+
+# Coverage report
+bun run test:coverage
+```
+
+## Git Workflow
+
+### Branch Strategy
+- `main` branch for stable releases
+- Feature branches: `feat/feature-name`
+- Bug fixes: `fix/bug-description`
+- Use conventional commit messages
+
+### Pre-commit Hooks
+Automatically run on every commit:
+- TypeScript type checking
+- Code linting (oxlint)
+- Code formatting check (Biome)
+- File size validation
+- ast-grep pattern checks
+- Tests for changed files
+
+### Pre-push Hooks
+Run before pushing to remote:
+- Full test suite
+- Code coverage validation
+- Complete build verification
+- All linting and formatting checks
+
+### Conventional Commits
+```bash
+feat: add support for patch comparison
+fix: handle empty diff responses
+docs: update API documentation
+test: add integration tests for diff command
+refactor: simplify error handling logic
+```
+
+## Adding New Commands
+
+### 1. Define Schema
+Add types to `src/schemas/gerrit.ts`:
+```typescript
+export const NewCommandOptions = Schema.Struct({
+  option1: Schema.String,
+  option2: Schema.optional(Schema.Number),
+})
+export type NewCommandOptions = Schema.Schema.Type<typeof NewCommandOptions>
+```
+
+### 2. Extend API Service
+Add methods to `src/api/gerrit.ts`:
+```typescript
+readonly newMethod: (param: string) => Effect.Effect<ReturnType, ApiError>
+```
+
+### 3. Create Command Component
+Create `src/cli/commands/new-command.tsx`:
+```typescript
+import React from 'react'
+import { Box, Text } from 'ink'
+// Implementation...
+```
+
+### 4. Register Command
+Add to `src/cli/index.ts`:
+```typescript
+program
+  .command('new-command <param>')
+  .description('Description of new command')
+  .action(/* implementation */)
+```
+
+### 5. Add Tests
+Create test files in `tests/unit/` and `tests/integration/`
+
+### 6. Update Documentation
+Update README.md with usage examples
+
+## Database Management
+
+### Schema Changes
+1. Update `src/db/schema.ts` with new tables/columns
+2. Add migration logic to `src/db/database.ts`
+3. Test with fresh database creation
+4. Update cache invalidation logic if needed
+
+### Caching Strategy
+- **Cache-first** - Always check local cache first
+- **Smart invalidation** - Update cache on write operations
+- **Offline support** - Gracefully handle network failures
+
+## MSW Mock Setup
+
+### Adding New API Endpoints
+1. Define response schema in `src/schemas/gerrit.ts`
+2. Add handler to `tests/mocks/handlers.ts`
+3. Use schema validation in mock responses
+4. Test both success and error cases
+
+### Mock Data Generation
+```typescript
+const mockData: Schema.Schema.Type<typeof YourSchema> = {
+  // Properly typed mock data
+}
+
+const validated = Schema.decodeUnknownSync(YourSchema)(mockData)
+return HttpResponse.json(validated)
+```
+
+## Performance Considerations
+
+### Caching
+- Cache API responses in SQLite
+- Implement cache expiration
+- Provide cache management commands
+
+### Bundle Size
+- Use dynamic imports for large dependencies
+- Tree-shake unused code
+- Monitor bundle size in CI
+
+### CLI Responsiveness
+- Show loading indicators
+- Stream large outputs
+- Implement request cancellation
+
+## Security Guidelines
+
+### Credential Storage
+- Store in `~/.gi/credentials.json` with 600 permissions
+- Never log credentials
+- Use secure environment variable handling
+
+### API Communication
+- Always use HTTPS
+- Validate all inputs with Effect Schema
+- Handle authentication errors gracefully
+
+### Error Messages
+- Never expose sensitive information
+- Provide helpful debugging information
+- Log errors for debugging without sensitive data
+
+## Release Process
+
+### Version Management
+- Use semantic versioning (semver)
+- Update version in `package.json`
+- Create git tags for releases
+
+### Build Process
+```bash
+bun run build              # Build optimized bundle
+bun test                   # Ensure all tests pass
+bun run check:all          # Run all quality checks
+```
+
+### Distribution
+- Create platform-specific binaries
+- Upload to GitHub releases
+- Update installation instructions
+
+## Contributing Guidelines
+
+### Code Review Checklist
+- [ ] All tests pass
+- [ ] Code coverage maintained
+- [ ] TypeScript strict mode compliance
+- [ ] Follows existing patterns
+- [ ] Documentation updated
+- [ ] Error handling implemented
+- [ ] Security considerations addressed
+
+### Pull Request Process
+1. Create feature branch
+2. Implement changes with tests
+3. Run `bun run check:all`
+4. Create pull request with description
+5. Address review feedback
+6. Merge after approval
+
+## Troubleshooting
+
+### Common Development Issues
+
+**Build failures**
+```bash
+rm -rf node_modules bun.lockb
+bun install
+```
+
+**Test failures**
+```bash
+bun test --verbose
+```
+
+**Type errors**
+```bash
+bun run typecheck
+```
+
+**Lint errors**
+```bash
+bun run format  # Auto-fix formatting
+bun run lint    # Check for issues
+```
+
+### Debug Mode
+```bash
+DEBUG=1 bun run dev <command>  # Enable debug logging
+```
+
+### Database Issues
+```bash
+rm -rf ~/.gi/cache.db  # Reset local cache
+```
+
+## Resources
+
+- [Effect Documentation](https://effect.website/)
+- [Ink Documentation](https://github.com/vadimdemedes/ink)
+- [Bun Documentation](https://bun.sh/docs)
+- [MSW Documentation](https://mswjs.io/)
+- [Gerrit REST API](https://gerrit-review.googlesource.com/Documentation/rest-api.html)

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Aaron Shafovaloff
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,325 @@
+# ger
+
+Gerrit CLI built with Bun. XML output by default for LLM/automation compatibility, human-readable output with `--pretty`.
+
+## Features
+
+- **LLM-Friendly**: XML output for AI/automation pipelines
+- **Interactive UI**: Terminal UI for change selection and navigation  
+- **Secure**: Credentials stored in system keychain
+- **Effect-based**: Robust error handling and functional architecture
+- **Batch Comments**: JSON array input with line/range targeting and side support
+
+## Installation
+
+```bash
+# Install Bun runtime
+curl -fsSL https://bun.sh/install | bash
+
+# Install ger
+bun install -g @aaronshaf/ger
+```
+
+## Getting Started
+
+```bash
+ger setup
+```
+
+This will prompt for your Gerrit credentials:
+- Gerrit host URL
+- Username
+- HTTP password (from Gerrit settings)
+
+Credentials are securely stored in your system keychain.
+
+## Common Commands
+
+### Daily Workflow
+
+```bash
+# Check your connection status
+ger status
+
+# View your changes
+ger mine
+
+# View incoming reviews
+ger incoming
+
+# View a specific change
+ger show 12345
+
+# Add a comment
+ger comment 12345 -m "LGTM"
+
+# Get diff for review
+ger diff 12345
+
+# AI-powered code review (requires claude, llm, or opencode CLI)
+ger review 12345
+ger review 12345 --dry-run  # Preview without posting
+```
+
+## Commands
+
+### Connection Status
+```bash
+ger status
+ger status --pretty
+```
+
+### Show Change Details
+```bash
+# Complete change info with metadata, diff, inline comments, and review activity
+ger show 12345
+ger show 12345 --pretty
+```
+
+### List Changes
+```bash
+# Your changes
+ger mine
+ger mine --pretty
+
+# Incoming reviews
+ger incoming
+ger incoming --pretty
+
+# Workspace changes (local branch tracking)
+ger workspace
+ger workspace --pretty
+```
+
+### Comments
+
+#### Overall Comments
+```bash
+# Using -m flag
+ger comment 12345 -m "LGTM"
+
+# Piping plain text (becomes overall comment message)
+echo "Review text" | ger comment 12345
+cat review.txt | ger comment 12345
+```
+
+#### Line-Specific Comments
+```bash
+# Single line comment (line numbers refer to post-merge view)
+ger comment 12345 --file src/main.ts --line 42 -m "Consider error handling"
+
+# Mark as unresolved
+ger comment 12345 --file src/main.ts --line 42 -m "Fix this" --unresolved
+```
+
+#### Batch Line Comments (JSON Array)
+
+The batch comment feature accepts a JSON array of comment objects. Each comment can target specific lines, ranges, or sides of the diff.
+
+##### Basic Structure
+```javascript
+[
+  {
+    "file": "path/to/file.js",       // Required: File path
+    "line": 42,                       // Optional: Line number (omit when using range)
+    "message": "Your comment",        // Required: Comment text
+    "side": "REVISION",               // Optional: "PARENT" or "REVISION" (default: REVISION)
+    "range": {                        // Optional: Comment on multiple lines or characters
+      "start_line": 10,
+      "end_line": 20,
+      "start_character": 0,           // Optional: Character position (0-indexed)
+      "end_character": 80
+    },
+    "unresolved": true                // Optional: Mark as unresolved (default: false)
+  }
+]
+```
+
+##### Examples
+
+```bash
+# Basic batch comments
+echo '[
+  {"file": "src/main.ts", "line": 10, "message": "Add type annotation"},
+  {"file": "src/utils.ts", "line": 25, "message": "Extract to constant"},
+  {"file": "src/api.ts", "line": 100, "message": "Handle error", "unresolved": true}
+]' | ger comment 12345 --batch
+
+# Comment on different sides of the diff
+# PARENT: The original code before changes
+# REVISION: The new code after changes
+echo '[
+  {"file": "src/Calculator.java", "line": 5, "side": "PARENT", "message": "Why was this removed?"},
+  {"file": "src/Calculator.java", "line": 5, "side": "REVISION", "message": "Good improvement"}
+]' | ger comment 12345 --batch
+
+# Range comments for blocks of code
+echo '[
+  {
+    "file": "src/Service.java",
+    "range": {"start_line": 50, "end_line": 55},
+    "message": "This entire method needs refactoring"
+  },
+  {
+    "file": "src/Service.java",
+    "range": {"start_line": 10, "start_character": 8, "end_line": 10, "end_character": 25},
+    "message": "This variable name is confusing"
+  }
+]' | ger comment 12345 --batch
+
+# Combined features: range + side + unresolved
+echo '[
+  {
+    "file": "src/UserService.java",
+    "range": {"start_line": 20, "end_line": 35},
+    "side": "PARENT",
+    "message": "Why was this error handling removed?",
+    "unresolved": true
+  },
+  {
+    "file": "src/UserService.java",
+    "range": {"start_line": 20, "end_line": 35},
+    "side": "REVISION",
+    "message": "New error handling looks good, but consider extracting to a method"
+  }
+]' | ger comment 12345 --batch
+
+# Load comments from a file
+cat comments.json | ger comment 12345 --batch
+```
+
+#### View Comments
+```bash
+# View all comments with diff context
+ger comments 12345
+ger comments 12345 --pretty
+```
+
+### Diff
+```bash
+# Full diff
+ger diff 12345
+ger diff 12345 --pretty
+
+# List changed files
+ger diff 12345 --files-only
+
+# Specific file
+ger diff 12345 --file src/main.ts
+```
+
+### Change Management
+```bash
+# Open in browser
+ger open 12345
+
+# Abandon
+ger abandon 12345
+ger abandon 12345 -m "Reason"
+```
+
+### AI-Powered Review
+
+The `ger review` command provides automated code review using AI tools (claude, llm, or opencode CLI).
+
+```bash
+# Full AI review with inline and overall comments
+ger review 12345
+
+# Preview what would be posted without actually posting
+ger review 12345 --dry-run
+
+# Show debug output including AI responses
+ger review 12345 --debug
+```
+
+The review command performs a two-stage review process:
+1. **Inline comments**: Specific code issues with line-by-line feedback
+2. **Overall review**: High-level assessment and recommendations
+
+Requirements:
+- One of these AI tools must be installed: `claude`, `llm`, or `opencode`
+- Gerrit credentials must be configured (`ger setup`)
+
+## LLM Integration
+
+```bash
+# Review with AI
+ger diff 12345 | llm "Review this code"
+
+# AI-generated comment
+llm "Review change 12345" | ger comment 12345
+
+# Complete change analysis
+ger show 12345 | llm "Summarize this change and its review status"
+
+# Automated approvals
+echo "LGTM" | ger comment 12345
+```
+
+## Output Formats
+
+### XML (Default)
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<comment_result>
+  <status>success</status>
+  <change_id>12345</change_id>
+  <message><![CDATA[LGTM]]></message>
+</comment_result>
+```
+
+### Pretty (--pretty flag)
+```
+Comment posted successfully
+Change: Fix authentication bug (NEW)
+Message: LGTM
+```
+
+## Upgrading
+
+To upgrade gi to the latest version:
+
+```bash
+bun update -g @aaronshaf/ger
+```
+
+After upgrading, you may want to review new configuration options:
+
+```bash
+ger setup  # Review and update your configuration
+```
+
+## Development
+
+For local development:
+
+```bash
+git clone https://github.com/aaronshaf/ger
+cd ger
+bun install
+
+# Run locally
+bun run dev
+
+# Run tests
+bun test
+bun run test:coverage
+
+# Type checking
+bun run typecheck
+
+# Linting
+bun run lint
+```
+
+### Stack
+- **Bun** - Runtime and package manager
+- **Effect** - Type-safe error handling and functional architecture
+- **TypeScript** - With isolatedDeclarations
+- **Ink** - Terminal UI components
+- **Commander** - CLI argument parsing
+
+## License
+
+MIT

package/bin/ger

@@ -0,0 +1,3 @@
+#!/usr/bin/env bun
+// Entry point for ger CLI
+import '../src/cli/index.ts'