@aaronshaf/ger 1.2.11 → 2.0.0

package/docs/prd/data-model.md

@@ -0,0 +1,349 @@
+# Data Model
+
+Schemas and data structures used throughout the application.
+
+## Gerrit API Types
+
+### ChangeInfo
+
+Primary change representation from Gerrit API.
+
+```typescript
+const ChangeInfo = Schema.Struct({
+  id: Schema.String,              // "project~branch~Change-Id"
+  _number: Schema.Number,         // Numeric change ID
+  project: Schema.String,         // Project name
+  branch: Schema.String,          // Target branch
+  topic: Schema.optional(Schema.String),
+  subject: Schema.String,         // First line of commit message
+  status: Schema.Literal('NEW', 'MERGED', 'ABANDONED', 'DRAFT'),
+  created: Schema.String,         // ISO timestamp
+  updated: Schema.String,         // ISO timestamp
+  submitted: Schema.optional(Schema.String),
+  submitter: Schema.optional(AccountInfo),
+  owner: AccountInfo,
+  current_revision: Schema.optional(Schema.String),
+  revisions: Schema.optional(Schema.Record(Schema.String, RevisionInfo)),
+  labels: Schema.optional(Schema.Record(Schema.String, LabelInfo)),
+  reviewers: Schema.optional(ReviewerMap),
+  messages: Schema.optional(Schema.Array(ChangeMessage)),
+  mergeable: Schema.optional(Schema.Boolean),
+  insertions: Schema.optional(Schema.Number),
+  deletions: Schema.optional(Schema.Number),
+})
+```
+
+### AccountInfo
+
+User account information.
+
+```typescript
+const AccountInfo = Schema.Struct({
+  _account_id: Schema.Number,
+  name: Schema.optional(Schema.String),
+  email: Schema.optional(Schema.String),
+  username: Schema.optional(Schema.String),
+  display_name: Schema.optional(Schema.String),
+})
+```
+
+### RevisionInfo
+
+Patchset revision details.
+
+```typescript
+const RevisionInfo = Schema.Struct({
+  _number: Schema.Number,         // Patchset number
+  kind: Schema.Literal(
+    'REWORK', 'TRIVIAL_REBASE', 'MERGE_FIRST_PARENT_UPDATE',
+    'NO_CODE_CHANGE', 'NO_CHANGE'
+  ),
+  created: Schema.String,
+  uploader: AccountInfo,
+  ref: Schema.String,             // Git ref (refs/changes/xx/xxxxx/x)
+  fetch: Schema.optional(Schema.Record(Schema.String, FetchInfo)),
+  commit: Schema.optional(CommitInfo),
+  files: Schema.optional(Schema.Record(Schema.String, FileInfo)),
+})
+```
+
+### CommentInfo
+
+Comment on a change.
+
+```typescript
+const CommentInfo = Schema.Struct({
+  id: Schema.String,
+  path: Schema.optional(Schema.String),
+  line: Schema.optional(Schema.Number),
+  range: Schema.optional(CommentRange),
+  message: Schema.String,
+  author: AccountInfo,
+  updated: Schema.String,
+  side: Schema.optional(Schema.Literal('PARENT', 'REVISION')),
+  unresolved: Schema.optional(Schema.Boolean),
+  in_reply_to: Schema.optional(Schema.String),
+})
+```
+
+### CommentRange
+
+Line range for inline comments.
+
+```typescript
+const CommentRange = Schema.Struct({
+  start_line: Schema.Number,
+  start_character: Schema.Number,
+  end_line: Schema.Number,
+  end_character: Schema.Number,
+})
+```
+
+### ChangeMessage
+
+Message/event on a change.
+
+```typescript
+const ChangeMessage = Schema.Struct({
+  id: Schema.String,
+  author: Schema.optional(AccountInfo),
+  date: Schema.String,
+  message: Schema.String,
+  tag: Schema.optional(Schema.String),
+  _revision_number: Schema.optional(Schema.Number),
+})
+```
+
+### LabelInfo
+
+Voting label information.
+
+```typescript
+const LabelInfo = Schema.Struct({
+  approved: Schema.optional(AccountInfo),
+  rejected: Schema.optional(AccountInfo),
+  recommended: Schema.optional(AccountInfo),
+  disliked: Schema.optional(AccountInfo),
+  value: Schema.optional(Schema.Number),
+  default_value: Schema.optional(Schema.Number),
+  all: Schema.optional(Schema.Array(ApprovalInfo)),
+  values: Schema.optional(Schema.Record(Schema.String, Schema.String)),
+})
+```
+
+### GroupInfo
+
+Gerrit group information.
+
+```typescript
+const GroupInfo = Schema.Struct({
+  id: Schema.String,
+  name: Schema.String,
+  url: Schema.optional(Schema.String),
+  options: Schema.optional(GroupOptions),
+  description: Schema.optional(Schema.String),
+  group_id: Schema.optional(Schema.Number),
+  owner: Schema.optional(Schema.String),
+  owner_id: Schema.optional(Schema.String),
+  created_on: Schema.optional(Schema.String),
+  members: Schema.optional(Schema.Array(AccountInfo)),
+  includes: Schema.optional(Schema.Array(GroupInfo)),
+})
+```
+
+## Configuration Schema
+
+### AppConfig
+
+Application configuration stored in `~/.ger/config.json`.
+
+```typescript
+const AppConfig = Schema.Struct({
+  host: Schema.String,            // Gerrit server URL
+  username: Schema.String,        // Gerrit username
+  password: Schema.String,        // HTTP password/token
+  aiTool: Schema.optional(Schema.String),      // Preferred AI tool
+  aiAutoDetect: Schema.optional(Schema.Boolean), // Auto-detect AI tool
+})
+```
+
+**File permissions:** 0600 (owner read/write only)
+
+## API Input Types
+
+### ReviewInput
+
+Input for posting reviews/comments.
+
+```typescript
+const ReviewInput = Schema.Struct({
+  message: Schema.optional(Schema.String),     // Overall comment
+  labels: Schema.optional(Schema.Record(Schema.String, Schema.Number)),
+  comments: Schema.optional(Schema.Record(
+    Schema.String,  // file path
+    Schema.Array(CommentInput)
+  )),
+  tag: Schema.optional(Schema.String),
+  notify: Schema.optional(Schema.Literal('NONE', 'OWNER', 'OWNER_REVIEWERS', 'ALL')),
+})
+```
+
+### CommentInput
+
+Input for a single inline comment.
+
+```typescript
+const CommentInput = Schema.Struct({
+  line: Schema.optional(Schema.Number),
+  range: Schema.optional(CommentRange),
+  message: Schema.String,
+  side: Schema.optional(Schema.Literal('PARENT', 'REVISION')),
+  unresolved: Schema.optional(Schema.Boolean),
+  in_reply_to: Schema.optional(Schema.String),
+})
+```
+
+### ReviewerInput
+
+Input for adding reviewers.
+
+```typescript
+const ReviewerInput = Schema.Struct({
+  reviewer: Schema.String,        // Username, email, or group
+  state: Schema.optional(Schema.Literal('REVIEWER', 'CC')),
+  notify: Schema.optional(Schema.Literal('NONE', 'OWNER', 'OWNER_REVIEWERS', 'ALL')),
+})
+```
+
+## Internal Types
+
+### BuildState
+
+CI build status.
+
+```typescript
+type BuildState = 'pending' | 'running' | 'success' | 'failure' | 'not_found'
+```
+
+### InlineComment
+
+CLI input format for batch comments.
+
+```typescript
+const InlineComment = Schema.Struct({
+  file: Schema.String,
+  line: Schema.optional(Schema.Number),
+  range: Schema.optional(CommentRange),
+  message: Schema.String,
+  side: Schema.optional(Schema.Literal('PARENT', 'REVISION')),
+  unresolved: Schema.optional(Schema.Boolean),
+})
+```
+
+### ChangeIdentifier
+
+Normalized change identifier.
+
+```typescript
+// Accepts:
+// - Numeric: "12345"
+// - Change-ID: "If5a3ae8cb5a107e187447802358417f311d0c4b1"
+// - Full triplet: "project~branch~Change-Id"
+// - URL: "https://gerrit.example.com/c/project/+/12345"
+
+const isChangeNumber = (id: string): boolean => /^\d+$/.test(id)
+const isChangeId = (id: string): boolean => /^I[0-9a-f]{40}$/i.test(id)
+```
+
+## Error Types
+
+### ApiError
+
+API call failures.
+
+```typescript
+class ApiError extends Schema.TaggedError<ApiError>()('ApiError', {
+  message: Schema.String,
+  statusCode: Schema.Number,
+  url: Schema.String,
+}) {}
+```
+
+### ConfigError
+
+Configuration issues.
+
+```typescript
+class ConfigError extends Schema.TaggedError<ConfigError>()('ConfigError', {
+  message: Schema.String,
+}) {}
+```
+
+### GitError
+
+Git operation failures.
+
+```typescript
+class GitError extends Schema.TaggedError<GitError>()('GitError', {
+  message: Schema.String,
+  exitCode: Schema.Number,
+}) {}
+```
+
+### NoChangeIdError
+
+Missing Change-ID in commit.
+
+```typescript
+class NoChangeIdError extends Schema.TaggedError<NoChangeIdError>()('NoChangeIdError', {
+  message: Schema.String,
+}) {}
+```
+
+## Output Formats
+
+### Text (Default)
+
+Human-readable colored output:
+```
+Change 12345: Fix login bug
+Project: canvas-lms
+Branch: main
+Status: NEW
+Owner: alice@example.com
+
+Files:
+  M src/login.ts
+  A src/auth.ts
+```
+
+### XML (--xml flag)
+
+LLM-friendly structured output:
+```xml
+<change>
+  <number>12345</number>
+  <subject><![CDATA[Fix login bug]]></subject>
+  <project>canvas-lms</project>
+  <branch>main</branch>
+  <status>NEW</status>
+  <owner>alice@example.com</owner>
+  <files>
+    <file action="M">src/login.ts</file>
+    <file action="A">src/auth.ts</file>
+  </files>
+</change>
+```
+
+### JSON
+
+Programmatic consumption:
+```json
+{
+  "_number": 12345,
+  "subject": "Fix login bug",
+  "project": "canvas-lms",
+  "branch": "main",
+  "status": "NEW"
+}
+```

package/docs/prd/overview.md

@@ -0,0 +1,124 @@
+# ger - Gerrit CLI Tool
+
+## Overview
+
+`ger` is a modern, LLM-friendly CLI tool and SDK for Gerrit Code Review. It provides comprehensive Gerrit workflow automation with AI integration, published as both a CLI tool and npm package.
+
+## Goals
+
+1. **Fast Gerrit operations** - Quick access to changes, diffs, comments without browser
+2. **AI integration** - LLM-friendly output and automated code review
+3. **Developer ergonomics** - Auto-detection, smart defaults, minimal configuration
+4. **Programmatic access** - SDK for building custom tools and automation
+5. **Type safety** - Full TypeScript with Effect for reliable operations
+
+## Non-Goals
+
+- Replace Gerrit web UI entirely (complex dashboards, admin)
+- Support Gerrit versions older than 3.0
+- Implement bidirectional sync (changes are created via git push)
+- Provide real-time notifications (use Gerrit's native features)
+
+## Design Decisions
+
+| Decision | Choice | Rationale |
+|----------|--------|-----------|
+| Language | TypeScript/Bun | Fast runtime, native TS, matches ji/cn projects |
+| Error handling | Effect library | Type-safe errors, composable operations |
+| CLI framework | Commander.js | Stable, simple, well-documented |
+| Output formats | Text, XML, JSON | Human + machine readable |
+| Credentials | `~/.ger/config.json` | Secure, standard pattern |
+| Git integration | Subprocess | No deps, full features, worktree support |
+| Validation | Effect Schema | Single source of truth, type inference |
+| Testing | MSW + Bun test | Fast, realistic API mocking |
+| AI tools | Strategy pattern | Vendor-agnostic, auto-detection |
+
+## User Personas
+
+### Individual Developer
+- Works on personal changes
+- Needs quick status checks
+- Wants CLI convenience over browser
+
+### Code Reviewer
+- Reviews multiple changes daily
+- Needs efficient navigation
+- Benefits from AI-assisted review
+
+### Automation Engineer
+- Builds CI/CD pipelines
+- Needs programmatic access
+- Requires JSON/XML output
+
+### Team Lead
+- Manages reviewers and groups
+- Tracks team's open changes
+- Assigns reviewers efficiently
+
+## Commands Overview
+
+| Category | Commands |
+|----------|----------|
+| **View** | `show`, `diff`, `comments`, `search` |
+| **Review** | `comment`, `vote`, `review`, `add-reviewer` |
+| **Manage** | `mine`, `incoming`, `abandon`, `restore` |
+| **Operations** | `checkout`, `push`, `rebase`, `submit` |
+| **Groups** | `groups`, `groups-show`, `groups-members` |
+| **Utilities** | `status`, `setup`, `open`, `extract-url`, `build-status` |
+
+## User Flows
+
+### First-time Setup
+
+```
+$ ger setup
+? Gerrit URL: https://gerrit.example.com
+? Username: john.doe
+? HTTP Password: ****
+✓ Configuration saved to ~/.ger/config.json
+✓ Connection verified
+```
+
+### Daily Code Review
+
+```
+$ ger incoming
+PROJECT: canvas-lms
+  12345  Fix login bug             alice       CR: +1
+  12346  Add dark mode             bob         CR: 0
+
+$ ger show 12345
+Change 12345: Fix login bug
+Author: alice@example.com
+Status: NEW
+...
+
+$ ger review 12345
+✓ AI review posted (3 inline comments, 1 overall comment)
+```
+
+### Submit a Change
+
+```
+$ git commit -m "Fix typo in README"
+$ ger push
+✓ Pushed to refs/for/main
+✓ Change 12347 created
+
+$ ger add-reviewer 12347 bob carol
+✓ Added 2 reviewers
+```
+
+## Success Metrics
+
+- Handle repositories with 10,000+ changes
+- Complete common operations in < 2 seconds
+- AI review completes in < 30 seconds
+- 80%+ test coverage maintained
+
+## References
+
+- [Gerrit REST API](https://gerrit-review.googlesource.com/Documentation/rest-api.html)
+- [Effect library](https://effect.website/)
+- [ji project](https://github.com/aaronshaf/ji) - JIRA CLI (same author)
+- [cn project](https://github.com/aaronshaf/cn) - Confluence CLI (same author)

package/index.ts

@@ -0,0 +1,219 @@
+/**
+ * @aaronshaf/ger - Gerrit CLI and SDK
+ *
+ * This package provides both a CLI tool and a programmatic API for interacting with Gerrit Code Review.
+ * Built with Effect-TS for type-safe, composable operations.
+ *
+ * @module
+ *
+ * @example Basic usage with Effect
+ * ```typescript
+ * import { Effect, pipe } from 'effect'
+ * import {
+ *   GerritApiService,
+ *   GerritApiServiceLive,
+ *   ConfigServiceLive,
+ * } from '@aaronshaf/ger'
+ *
+ * const program = Effect.gen(function* () {
+ *   const api = yield* GerritApiService
+ *   const change = yield* api.getChange('12345')
+ *   console.log(change.subject)
+ * })
+ *
+ * const runnable = pipe(
+ *   program,
+ *   Effect.provide(GerritApiServiceLive),
+ *   Effect.provide(ConfigServiceLive)
+ * )
+ *
+ * Effect.runPromise(runnable)
+ * ```
+ */
+
+// ============================================================================
+// Core API Service
+// ============================================================================
+
+export {
+  // Service tag and implementation
+  GerritApiService,
+  GerritApiServiceLive,
+  // Types
+  type GerritApiServiceImpl,
+  // Errors
+  ApiError,
+  type ApiErrorFields,
+} from './src/api/gerrit'
+
+// ============================================================================
+// Configuration Service
+// ============================================================================
+
+export {
+  // Service tag and implementation
+  ConfigService,
+  ConfigServiceLive,
+  // Types
+  type ConfigServiceImpl,
+  // Errors
+  ConfigError,
+  type ConfigErrorFields,
+} from './src/services/config'
+
+// ============================================================================
+// Review Strategy Service
+// ============================================================================
+
+export {
+  // Strategy types
+  type ReviewStrategy,
+  // Built-in strategies
+  claudeCliStrategy,
+  geminiCliStrategy,
+  openCodeCliStrategy,
+  // Service
+  ReviewStrategyService,
+  ReviewStrategyServiceLive,
+  type ReviewStrategyServiceImpl,
+  // Errors
+  ReviewStrategyError,
+  type ReviewStrategyErrorFields,
+} from './src/services/review-strategy'
+
+// ============================================================================
+// Git Worktree Service
+// ============================================================================
+
+export {
+  // Service tag and implementation
+  GitWorktreeService,
+  GitWorktreeServiceLive,
+  type GitWorktreeServiceImpl,
+  // Types
+  type WorktreeInfo,
+  // Errors
+  WorktreeCreationError,
+  type WorktreeCreationErrorFields,
+  PatchsetFetchError,
+  type PatchsetFetchErrorFields,
+  DirtyRepoError,
+  type DirtyRepoErrorFields,
+  NotGitRepoError,
+  type NotGitRepoErrorFields,
+  type GitWorktreeError,
+} from './src/services/git-worktree'
+
+// ============================================================================
+// Schemas and Types
+// ============================================================================
+
+export {
+  // Authentication
+  GerritCredentials,
+  type GerritCredentials as GerritCredentialsType,
+  // Changes
+  ChangeInfo,
+  type ChangeInfo as ChangeInfoType,
+  // Comments
+  CommentInput,
+  type CommentInput as CommentInputType,
+  CommentInfo,
+  type CommentInfo as CommentInfoType,
+  // Messages
+  MessageInfo,
+  type MessageInfo as MessageInfoType,
+  // Reviews
+  ReviewInput,
+  type ReviewInput as ReviewInputType,
+  // Files and Diffs
+  FileInfo,
+  type FileInfo as FileInfoType,
+  FileDiffContent,
+  type FileDiffContent as FileDiffContentType,
+  RevisionInfo,
+  type RevisionInfo as RevisionInfoType,
+  // Diff Options
+  DiffFormat,
+  type DiffFormat as DiffFormatType,
+  DiffOptions,
+  type DiffOptions as DiffOptionsType,
+  DiffCommandOptions,
+  type DiffCommandOptions as DiffCommandOptionsType,
+  // Errors
+  GerritError,
+  type GerritError as GerritErrorType,
+} from './src/schemas/gerrit'
+
+export {
+  // Config schemas
+  AppConfig,
+  type AppConfig as AppConfigType,
+  AiConfig,
+  type AiConfig as AiConfigType,
+  // Utilities
+  aiConfigFromFlat,
+  migrateFromNestedConfig,
+} from './src/schemas/config'
+
+// ============================================================================
+// Utilities
+// ============================================================================
+
+export {
+  // Change ID handling
+  normalizeChangeIdentifier,
+  isChangeId,
+  isChangeNumber,
+  isValidChangeIdentifier,
+  getIdentifierType,
+} from './src/utils/change-id'
+
+export {
+  // Git commit utilities
+  extractChangeIdFromCommitMessage,
+  getLastCommitMessage,
+  getChangeIdFromHead,
+  GitError,
+  NoChangeIdError,
+} from './src/utils/git-commit'
+
+export {
+  // URL parsing
+  extractChangeNumber,
+  normalizeGerritHost,
+  isValidChangeId,
+} from './src/utils/url-parser'
+
+export {
+  // Message filtering
+  filterMeaningfulMessages,
+  sortMessagesByDate,
+} from './src/utils/message-filters'
+
+export {
+  // Shell safety
+  sanitizeCDATA,
+} from './src/utils/shell-safety'
+
+export {
+  // Formatters
+  formatDate,
+  getStatusIndicator,
+  colors,
+} from './src/utils/formatters'
+
+export {
+  // Comment formatters
+  formatCommentsPretty,
+  formatCommentsXml,
+  type CommentWithContext,
+} from './src/utils/comment-formatters'
+
+export {
+  // Diff formatters
+  formatDiffPretty,
+  formatDiffSummary,
+  formatFilesList,
+  extractDiffStats,
+} from './src/utils/diff-formatters'

package/oxlint.json

@@ -0,0 +1,24 @@
+{
+  "rules": {
+    "no-implicit-any": "error",
+    "no-explicit-any": "error",
+    "no-unused-vars": "error",
+    "no-console": "warn",
+    "no-debugger": "error",
+    "prefer-const": "error",
+    "no-var": "error",
+    "eqeqeq": "error",
+    "no-eval": "error"
+  },
+  "ignorePatterns": [
+    "node_modules",
+    "dist",
+    "tmp",
+    "**/*.js",
+    "**/*.jsx",
+    "**/*.tsx",
+    "coverage",
+    "*.config.js",
+    "*.config.ts"
+  ]
+}