@aaronshaf/ger 0.2.1 → 0.2.2

package/EXAMPLES.md

@@ -0,0 +1,409 @@
+# Programmatic Usage Examples
+
+This package can be used both as a CLI tool and as a library. Below are examples of using `@aaronshaf/ger` programmatically with Effect-TS.
+
+## Installation
+
+```bash
+bun add @aaronshaf/ger
+# or
+npm install @aaronshaf/ger
+```
+
+## Basic Setup
+
+All services in this package are built with Effect-TS, providing type-safe, composable operations.
+
+### Import the services
+
+```typescript
+import { Effect, pipe } from 'effect'
+import {
+  GerritApiService,
+  GerritApiServiceLive,
+  ConfigServiceLive,
+  type ChangeInfo,
+} from '@aaronshaf/ger'
+```
+
+## Configuration
+
+### Using Environment Variables
+
+Set these environment variables before running your program:
+
+```bash
+export GERRIT_HOST="https://gerrit.example.com"
+export GERRIT_USERNAME="your-username"
+export GERRIT_PASSWORD="your-http-password"
+```
+
+### Using File-Based Config
+
+Or run the CLI once to set up configuration:
+
+```bash
+ger setup
+```
+
+This stores credentials in `~/.ger/config.json`.
+
+## Examples
+
+### 1. Get Change Information
+
+```typescript
+import { Effect, pipe } from 'effect'
+import {
+  GerritApiService,
+  GerritApiServiceLive,
+  ConfigServiceLive,
+} from '@aaronshaf/ger'
+
+const getChangeDetails = (changeId: string) =>
+  Effect.gen(function* () {
+    const api = yield* GerritApiService
+    const change = yield* api.getChange(changeId)
+
+    console.log(`Change: ${change.subject}`)
+    console.log(`Status: ${change.status}`)
+    console.log(`Owner: ${change.owner?.name || 'Unknown'}`)
+
+    return change
+  })
+
+// Run the program
+const program = pipe(
+  getChangeDetails('12345'),
+  Effect.provide(GerritApiServiceLive),
+  Effect.provide(ConfigServiceLive)
+)
+
+Effect.runPromise(program)
+  .then(() => console.log('Done!'))
+  .catch(console.error)
+```
+
+### 2. List Open Changes
+
+```typescript
+import { Effect, pipe } from 'effect'
+import {
+  GerritApiService,
+  GerritApiServiceLive,
+  ConfigServiceLive,
+} from '@aaronshaf/ger'
+
+const listMyChanges = Effect.gen(function* () {
+  const api = yield* GerritApiService
+
+  // Query for your open changes
+  const changes = yield* api.listChanges('is:open owner:self')
+
+  console.log(`You have ${changes.length} open changes:`)
+  for (const change of changes) {
+    console.log(`  - #${change._number}: ${change.subject}`)
+  }
+
+  return changes
+})
+
+const program = pipe(
+  listMyChanges,
+  Effect.provide(GerritApiServiceLive),
+  Effect.provide(ConfigServiceLive)
+)
+
+Effect.runPromise(program).catch(console.error)
+```
+
+### 3. Post a Comment
+
+```typescript
+import { Effect, pipe } from 'effect'
+import {
+  GerritApiService,
+  GerritApiServiceLive,
+  ConfigServiceLive,
+  type ReviewInput,
+} from '@aaronshaf/ger'
+
+const postComment = (changeId: string) =>
+  Effect.gen(function* () {
+    const api = yield* GerritApiService
+
+    const review: ReviewInput = {
+      message: 'Looks good to me!',
+      labels: {
+        'Code-Review': 1,
+      },
+    }
+
+    yield* api.postReview(changeId, review)
+    console.log('Comment posted successfully!')
+  })
+
+const program = pipe(
+  postComment('12345'),
+  Effect.provide(GerritApiServiceLive),
+  Effect.provide(ConfigServiceLive)
+)
+
+Effect.runPromise(program).catch(console.error)
+```
+
+### 4. Post Inline Comments
+
+```typescript
+import { Effect, pipe } from 'effect'
+import {
+  GerritApiService,
+  GerritApiServiceLive,
+  ConfigServiceLive,
+  type ReviewInput,
+} from '@aaronshaf/ger'
+
+const postInlineComments = (changeId: string) =>
+  Effect.gen(function* () {
+    const api = yield* GerritApiService
+
+    const review: ReviewInput = {
+      message: 'Review complete',
+      comments: {
+        'src/api.ts': [
+          {
+            line: 42,
+            message: 'Consider using const here for immutability',
+            unresolved: false,
+          },
+          {
+            line: 55,
+            message: 'This could cause a security issue',
+            unresolved: true,
+          },
+        ],
+        'src/utils.ts': [
+          {
+            line: 10,
+            message: 'Nice refactor!',
+          },
+        ],
+      },
+    }
+
+    yield* api.postReview(changeId, review)
+    console.log('Inline comments posted!')
+  })
+
+const program = pipe(
+  postInlineComments('12345'),
+  Effect.provide(GerritApiServiceLive),
+  Effect.provide(ConfigServiceLive)
+)
+
+Effect.runPromise(program).catch(console.error)
+```
+
+### 5. Get Diff for a Change
+
+```typescript
+import { Effect, pipe } from 'effect'
+import {
+  GerritApiService,
+  GerritApiServiceLive,
+  ConfigServiceLive,
+  type DiffOptions,
+} from '@aaronshaf/ger'
+
+const getDiff = (changeId: string) =>
+  Effect.gen(function* () {
+    const api = yield* GerritApiService
+
+    // Get unified diff format (default)
+    const diff = yield* api.getDiff(changeId, { format: 'unified' })
+    console.log('Diff:', diff)
+
+    // Or get list of changed files
+    const files = yield* api.getDiff(changeId, { format: 'files' })
+    console.log('Changed files:', files)
+
+    return diff
+  })
+
+const program = pipe(
+  getDiff('12345'),
+  Effect.provide(GerritApiServiceLive),
+  Effect.provide(ConfigServiceLive)
+)
+
+Effect.runPromise(program).catch(console.error)
+```
+
+### 6. Test Connection
+
+```typescript
+import { Effect, pipe } from 'effect'
+import {
+  GerritApiService,
+  GerritApiServiceLive,
+  ConfigServiceLive,
+} from '@aaronshaf/ger'
+
+const testConnection = Effect.gen(function* () {
+  const api = yield* GerritApiService
+  const isConnected = yield* api.testConnection
+
+  if (isConnected) {
+    console.log('✓ Connected to Gerrit!')
+  } else {
+    console.log('✗ Connection failed')
+  }
+
+  return isConnected
+})
+
+const program = pipe(
+  testConnection,
+  Effect.provide(GerritApiServiceLive),
+  Effect.provide(ConfigServiceLive)
+)
+
+Effect.runPromise(program).catch(console.error)
+```
+
+### 7. Error Handling with Effect
+
+```typescript
+import { Effect, pipe, Console } from 'effect'
+import {
+  GerritApiService,
+  GerritApiServiceLive,
+  ConfigServiceLive,
+  ApiError,
+  ConfigError,
+} from '@aaronshaf/ger'
+
+const safeGetChange = (changeId: string) =>
+  Effect.gen(function* () {
+    const api = yield* GerritApiService
+    const change = yield* api.getChange(changeId)
+    return change
+  }).pipe(
+    Effect.catchTag('ApiError', (error) =>
+      Console.error(`API Error: ${error.message}`).pipe(
+        Effect.map(() => null)
+      )
+    ),
+    Effect.catchTag('ConfigError', (error) =>
+      Console.error(`Config Error: ${error.message}`).pipe(
+        Effect.map(() => null)
+      )
+    )
+  )
+
+const program = pipe(
+  safeGetChange('invalid-change'),
+  Effect.provide(GerritApiServiceLive),
+  Effect.provide(ConfigServiceLive)
+)
+
+Effect.runPromise(program)
+```
+
+### 8. Using Utilities
+
+```typescript
+import {
+  normalizeChangeIdentifier,
+  extractChangeIdFromCommitMessage,
+  extractChangeNumber,
+  normalizeGerritHost,
+} from '@aaronshaf/ger'
+
+// Normalize change identifiers
+const normalized = normalizeChangeIdentifier('12345')
+// or
+const normalizedId = normalizeChangeIdentifier('If5a3ae8cb5a107e187447802358417f311d0c4b1')
+
+// Extract change ID from commit message
+const commitMsg = `feat: add feature
+
+Change-Id: If5a3ae8cb5a107e187447802358417f311d0c4b1`
+
+const changeId = extractChangeIdFromCommitMessage(commitMsg)
+console.log(changeId) // "If5a3ae8cb5a107e187447802358417f311d0c4b1"
+
+// Extract change number from Gerrit URL
+const url = 'https://gerrit.example.com/c/project/+/12345'
+const changeNumber = extractChangeNumber(url)
+console.log(changeNumber) // "12345"
+
+// Normalize Gerrit host
+const host = normalizeGerritHost('gerrit.example.com')
+console.log(host) // "https://gerrit.example.com"
+```
+
+### 9. Working with Schemas
+
+```typescript
+import { Schema } from '@effect/schema'
+import { Effect } from 'effect'
+import { ChangeInfo, ReviewInput } from '@aaronshaf/ger'
+
+// Validate and decode API responses
+const validateChange = (data: unknown) =>
+  Schema.decodeUnknown(ChangeInfo)(data)
+
+// Validate review input before sending
+const validateReview = (review: unknown) =>
+  Schema.decodeUnknown(ReviewInput)(review)
+
+// Use in an Effect program
+const safeReview = Effect.gen(function* () {
+  const review = {
+    message: 'LGTM',
+    labels: { 'Code-Review': 2 },
+  }
+
+  const validated = yield* validateReview(review)
+  console.log('Review is valid:', validated)
+
+  return validated
+})
+```
+
+## Direct Module Access
+
+You can also import directly from specific modules:
+
+```typescript
+// Import from specific services
+import { GerritApiService, GerritApiServiceLive } from '@aaronshaf/ger/api'
+import { ConfigService, ConfigServiceLive } from '@aaronshaf/ger/services/config'
+
+// Import from specific schemas
+import { ChangeInfo, ReviewInput } from '@aaronshaf/ger/schemas/gerrit'
+
+// Import utilities
+import { normalizeChangeIdentifier, extractChangeNumber } from '@aaronshaf/ger/utils'
+```
+
+## TypeScript Configuration
+
+Make sure your `tsconfig.json` includes:
+
+```json
+{
+  "compilerOptions": {
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "strict": true
+  }
+}
+```
+
+## More Information
+
+- See the [main README](./README.md) for CLI usage
+- Check out the [Effect documentation](https://effect.website/) to learn more about Effect-TS
+- View the type definitions in your IDE for detailed API documentation

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/package.json

@@ -1,11 +1,56 @@
 {
   "name": "@aaronshaf/ger",
-  "version": "0.2.1",
+  "version": "0.2.2",
+  "description": "Gerrit CLI and SDK - A modern CLI tool and TypeScript SDK for Gerrit Code Review, built with Effect-TS",
+  "keywords": [
+    "gerrit",
+    "code-review",
+    "cli",
+    "sdk",
+    "effect",
+    "effect-ts",
+    "typescript",
+    "api-client"
+  ],
   "module": "index.ts",
   "type": "module",
   "bin": {
     "ger": "./bin/ger"
   },
+  "exports": {
+    ".": {
+      "import": "./index.ts",
+      "types": "./index.ts"
+    },
+    "./api": {
+      "import": "./src/api/gerrit.ts",
+      "types": "./src/api/gerrit.ts"
+    },
+    "./services/config": {
+      "import": "./src/services/config.ts",
+      "types": "./src/services/config.ts"
+    },
+    "./services/review-strategy": {
+      "import": "./src/services/review-strategy.ts",
+      "types": "./src/services/review-strategy.ts"
+    },
+    "./services/git-worktree": {
+      "import": "./src/services/git-worktree.ts",
+      "types": "./src/services/git-worktree.ts"
+    },
+    "./schemas/gerrit": {
+      "import": "./src/schemas/gerrit.ts",
+      "types": "./src/schemas/gerrit.ts"
+    },
+    "./schemas/config": {
+      "import": "./src/schemas/config.ts",
+      "types": "./src/schemas/config.ts"
+    },
+    "./utils": {
+      "import": "./src/utils/index.ts",
+      "types": "./src/utils/index.ts"
+    }
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/aaronshaf/ger.git"

package/src/services/git-worktree.ts

@@ -84,7 +84,11 @@ export class NotGitRepoError
   readonly name = 'NotGitRepoError'
 }
 
-export type GitError = WorktreeCreationError | PatchsetFetchError | DirtyRepoError | NotGitRepoError
+export type GitWorktreeError =
+  | WorktreeCreationError
+  | PatchsetFetchError
+  | DirtyRepoError
+  | NotGitRepoError
 
 // Worktree info
 export interface WorktreeInfo {
@@ -99,8 +103,8 @@ export interface WorktreeInfo {
 const runGitCommand = (
   args: string[],
   options: { cwd?: string } = {},
-): Effect.Effect<string, GitError, never> =>
-  Effect.async<string, GitError, never>((resume) => {
+): Effect.Effect<string, GitWorktreeError, never> =>
+  Effect.async<string, GitWorktreeError, never>((resume) => {
     const child = spawn('git', args, {
       cwd: options.cwd || process.cwd(),
       stdio: ['ignore', 'pipe', 'pipe'],
@@ -182,7 +186,7 @@ const buildRefspec = (changeNumber: string, patchsetNumber: number = 1): string
 }
 
 // Get the current HEAD commit hash to avoid branch conflicts
-const getCurrentCommit = (): Effect.Effect<string, GitError, never> =>
+const getCurrentCommit = (): Effect.Effect<string, GitWorktreeError, never> =>
   pipe(
     runGitCommand(['rev-parse', 'HEAD']),
     Effect.map((output) => output.trim()),
@@ -226,11 +230,13 @@ const getLatestPatchsetNumber = (
 
 // GitWorktreeService implementation
 export interface GitWorktreeServiceImpl {
-  validatePreconditions: () => Effect.Effect<void, GitError, never>
-  createWorktree: (changeId: string) => Effect.Effect<WorktreeInfo, GitError, never>
-  fetchAndCheckoutPatchset: (worktreeInfo: WorktreeInfo) => Effect.Effect<void, GitError, never>
+  validatePreconditions: () => Effect.Effect<void, GitWorktreeError, never>
+  createWorktree: (changeId: string) => Effect.Effect<WorktreeInfo, GitWorktreeError, never>
+  fetchAndCheckoutPatchset: (
+    worktreeInfo: WorktreeInfo,
+  ) => Effect.Effect<void, GitWorktreeError, never>
   cleanup: (worktreeInfo: WorktreeInfo) => Effect.Effect<void, never, never>
-  getChangedFiles: () => Effect.Effect<string[], GitError, never>
+  getChangedFiles: () => Effect.Effect<string[], GitWorktreeError, never>
 }
 
 const GitWorktreeServiceImplLive: GitWorktreeServiceImpl = {

package/src/utils/index.ts

@@ -0,0 +1,55 @@
+/**
+ * Utility functions for working with Gerrit
+ * @module utils
+ */
+
+// Change ID utilities
+export {
+  normalizeChangeIdentifier,
+  isChangeId,
+  isChangeNumber,
+  isValidChangeIdentifier,
+  getIdentifierType,
+} from './change-id'
+
+// Git commit utilities
+export {
+  extractChangeIdFromCommitMessage,
+  getLastCommitMessage,
+  getChangeIdFromHead,
+  GitError,
+  NoChangeIdError,
+} from './git-commit'
+
+// URL parsing
+export {
+  extractChangeNumber,
+  normalizeGerritHost,
+  isValidChangeId,
+} from './url-parser'
+
+// Message filtering
+export { filterMeaningfulMessages, sortMessagesByDate } from './message-filters'
+
+// Shell safety
+export { sanitizeCDATA } from './shell-safety'
+
+// Formatters
+export {
+  formatDate,
+  getStatusIndicator,
+  colors,
+} from './formatters'
+
+export {
+  formatCommentsPretty,
+  formatCommentsXml,
+  type CommentWithContext,
+} from './comment-formatters'
+
+export {
+  formatDiffPretty,
+  formatDiffSummary,
+  formatFilesList,
+  extractDiffStats,
+} from './diff-formatters'