@aaronshaf/ger 2.0.1 → 2.0.2

package/README.md

@@ -421,6 +421,22 @@ ger diff 12345 --file src/main.ts
 
 ### Change Management
 
+#### Install Commit-Msg Hook
+```bash
+# Install the Gerrit commit-msg hook
+ger install-hook
+
+# Force reinstall (overwrite existing)
+ger install-hook --force
+```
+
+**What it does:**
+- Downloads the commit-msg hook from your configured Gerrit server
+- Installs to `.git/hooks/commit-msg` with executable permissions
+- Required for commits to have Change-Id footers
+
+**Note:** The `push` command auto-installs the hook if missing, but you can use this command to manually install or update it.
+
 #### Checkout Changes
 ```bash
 # Checkout latest patchset

package/docs/prd/commands.md

@@ -129,6 +129,55 @@ ger workspace
 
 **Output:** Current branch and associated Gerrit change.
 
+### topic
+
+Get, set, or remove topic for a change.
+
+```bash
+ger topic [change-id]              # View current topic (auto-detect from HEAD)
+ger topic [change-id] <topic>      # Set topic
+ger topic [change-id] --delete     # Remove topic
+ger topic [change-id] --xml        # XML output
+```
+
+| Option | Description |
+|--------|-------------|
+| `--delete` | Remove the topic from the change |
+| `--xml` | Output as XML for LLM consumption |
+
+**Output formats:**
+
+Text (get):
+```
+my-feature
+```
+
+Text (set):
+```
+✓ Set topic on change 12345: my-feature
+```
+
+Text (delete):
+```
+✓ Removed topic from change 12345
+```
+
+XML:
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<topic_result>
+  <status>success</status>
+  <action>get|set|deleted</action>
+  <change_id><![CDATA[12345]]></change_id>
+  <topic><![CDATA[my-feature]]></topic>
+</topic_result>
+```
+
+**Use cases:**
+- Group related changes under a common topic
+- Filter changes by topic in Gerrit UI
+- Organize work for releases or features
+
 ## Code Review
 
 ### comment
@@ -370,6 +419,28 @@ ger init  # Alias
 
 **Creates:** `~/.ger/config.json` with secure permissions.
 
+### install-hook
+
+Install the Gerrit commit-msg hook for automatic Change-Id generation.
+
+```bash
+ger install-hook
+ger install-hook --force  # Overwrite existing hook
+```
+
+| Option | Description |
+|--------|-------------|
+| `--force` | Overwrite existing hook |
+| `--xml` | Output as XML |
+
+**Downloads:** Hook from configured Gerrit server.
+**Installs to:** `.git/hooks/commit-msg` (executable).
+
+**Use cases:**
+- Set up a new clone before first push
+- Repair corrupted hook
+- Update hook after Gerrit upgrade
+
 ### open
 
 Open change in browser.

package/llms.txt

@@ -0,0 +1,217 @@
+# ger
+
+> CLI for Gerrit code review. Query changes, post comments, vote, manage reviewers, checkout/push code, check build status. Supports XML output for LLM pipelines.
+
+## Installation
+
+```bash
+bun install -g @aaronshaf/ger
+ger setup  # Configure credentials interactively
+```
+
+## Change Identifiers
+
+Commands accept change number (12345) or Change-ID (If5a3ae8...). Many commands auto-detect from HEAD commit when omitted.
+
+## Commands
+
+### View Changes
+
+```bash
+ger show [change-id]              # Full change info: metadata, diff, comments
+ger show --xml                    # XML output for LLM consumption
+ger diff <change-id>              # Get diff
+ger diff <change-id> --files-only # List changed files only
+ger comments <change-id>          # View all comments with context
+ger search "owner:self status:open"  # Gerrit query syntax
+ger search "project:foo" -n 10    # Limit results
+```
+
+### List Changes
+
+```bash
+ger mine                  # Your open changes
+ger incoming              # Changes awaiting your review
+```
+
+### Post Comments
+
+```bash
+ger comment <change-id> -m "LGTM"                           # Overall comment
+echo "Review text" | ger comment <change-id>                # Piped input
+ger comment <change-id> --file src/foo.ts --line 42 -m "Fix this"  # Line comment
+ger comment <change-id> --file src/foo.ts --line 42 -m "Bug" --unresolved
+```
+
+Batch comments via JSON stdin:
+
+```bash
+echo '[
+  {"file": "src/main.ts", "line": 10, "message": "Add type annotation"},
+  {"file": "src/api.ts", "line": 25, "message": "Handle error", "unresolved": true}
+]' | ger comment <change-id> --batch
+```
+
+JSON schema: `{"file": string, "line": number, "message": string, "unresolved"?: boolean, "side"?: "PARENT"|"REVISION", "range"?: {start_line, end_line, start_character?, end_character?}}`
+
+### Vote
+
+```bash
+ger vote <change-id> --code-review +2
+ger vote <change-id> --code-review +2 --verified +1 -m "LGTM"
+ger vote <change-id> --label "Custom-Label" +1
+```
+
+### Manage Reviewers
+
+```bash
+ger add-reviewer user@example.com -c <change-id>
+ger add-reviewer user1 user2 -c <change-id>
+ger add-reviewer --group team-name -c <change-id>
+ger add-reviewer --cc user@example.com -c <change-id>
+ger remove-reviewer user@example.com -c <change-id>
+```
+
+### Topic Management
+
+```bash
+ger topic <change-id>              # View current topic
+ger topic <change-id> my-feature   # Set topic
+ger topic <change-id> --delete     # Remove topic
+```
+
+### Git Operations
+
+```bash
+ger checkout <change-id>           # Fetch and checkout change
+ger checkout <change-id> --detach  # Detached HEAD
+ger push                           # Push for review
+ger push -r alice@example.com -t my-topic --wip
+ger push --dry-run                 # Preview push
+```
+
+### Change Lifecycle
+
+```bash
+ger rebase [change-id]             # Rebase onto target branch
+ger submit <change-id>             # Submit for merge
+ger abandon <change-id> -m "reason"
+ger restore <change-id>
+```
+
+### Build Status
+
+```bash
+ger build-status [change-id]                    # Check status: pending|running|success|failure
+ger build-status --watch                        # Poll until completion
+ger build-status --watch --exit-status && deploy.sh  # Exit 1 on failure
+```
+
+### Extract URLs
+
+```bash
+ger extract-url "build-summary-report" | tail -1   # Latest Jenkins URL
+ger extract-url "jenkins" --json | jq -r '.urls[-1]'
+```
+
+### AI Review
+
+```bash
+ger review <change-id>              # AI-powered review (requires claude/gemini/opencode CLI)
+ger review <change-id> --tool claude
+ger review <change-id> --comment --yes  # Post review comments
+```
+
+### Groups
+
+```bash
+ger groups                         # List groups
+ger groups --pattern "^team-.*"    # Filter by regex
+ger groups-show <group-id>         # Group details
+ger groups-members <group-id>      # List members
+```
+
+### Utilities
+
+```bash
+ger status                         # Check connection
+ger open <change-id>               # Open in browser
+ger install-hook                   # Install commit-msg hook
+ger projects                       # List projects
+```
+
+## Output Formats
+
+Most commands support `--xml` for structured LLM output:
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<comment_result>
+  <status>success</status>
+  <change_id>12345</change_id>
+</comment_result>
+```
+
+Some commands also support `--json`.
+
+## Gerrit Query Syntax
+
+Common operators for `ger search`:
+
+- `owner:USER` - Changes owned by user (use 'self' for yourself)
+- `status:STATE` - open, merged, abandoned
+- `project:NAME` - Filter by project
+- `branch:NAME` - Filter by branch
+- `reviewer:USER` - Changes where user is reviewer
+- `is:wip` - Work-in-progress
+- `is:submittable` - Ready to submit
+- `age:TIME` - Time since update (1d, 2w, 1mon)
+- `label:Code-Review+2` - Filter by vote
+
+## Common Workflows
+
+### Review a change
+
+```bash
+ger show 12345                     # View change
+ger diff 12345                     # See code changes
+ger comment 12345 -m "LGTM"        # Add comment
+ger vote 12345 --code-review +2    # Approve
+```
+
+### Post AI review
+
+```bash
+ger review 12345 --comment --yes
+```
+
+### Check build and get failures
+
+```bash
+ger build-status --watch --exit-status
+ger extract-url "build-summary-report" | tail -1  # Get Jenkins URL
+```
+
+### Push with reviewers
+
+```bash
+ger push -r alice@example.com -r bob@example.com -t feature-topic
+```
+
+## Exit Codes
+
+- `0` - Success
+- `1` - Error (or build failure with --exit-status)
+- `2` - Timeout
+- `3` - API/network error
+
+## Configuration
+
+Credentials stored in `~/.ger/config.json`. Run `ger setup` to configure:
+- Gerrit host URL
+- Username
+- HTTP password (from Gerrit settings)
+
+## Links
+
+- [Gerrit Query Syntax](https://gerrit-review.googlesource.com/Documentation/user-search.html)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aaronshaf/ger",
-  "version": "2.0.1",
+  "version": "2.0.2",
   "description": "Gerrit CLI and SDK - A modern CLI tool and TypeScript SDK for Gerrit Code Review, built with Effect-TS",
   "keywords": [
     "gerrit",

package/src/api/gerrit.ts

@@ -90,26 +90,25 @@ export interface GerritApiServiceImpl {
     accountId: string,
     options?: { notify?: 'NONE' | 'OWNER' | 'OWNER_REVIEWERS' | 'ALL' },
   ) => Effect.Effect<void, ApiError>
+  readonly getTopic: (changeId: string) => Effect.Effect<string | null, ApiError>
+  readonly setTopic: (changeId: string, topic: string) => Effect.Effect<string, ApiError>
+  readonly deleteTopic: (changeId: string) => Effect.Effect<void, ApiError>
 }
 
-// Export both the tag value and the type for use in Effect requirements
 export const GerritApiService: Context.Tag<GerritApiServiceImpl, GerritApiServiceImpl> =
   Context.GenericTag<GerritApiServiceImpl>('GerritApiService')
 export type GerritApiService = Context.Tag.Identifier<typeof GerritApiService>
 
-// Export ApiError fields interface explicitly
 export interface ApiErrorFields {
   readonly message: string
   readonly status?: number
 }
 
-// Define error schema (not exported, so type can be implicit)
 const ApiErrorSchema = Schema.TaggedError<ApiErrorFields>()('ApiError', {
   message: Schema.String,
   status: Schema.optional(Schema.Number),
 } as const) as unknown
 
-// Export the error class with explicit constructor signature for isolatedDeclarations
 export class ApiError
   extends (ApiErrorSchema as new (
     args: ApiErrorFields,
@@ -127,7 +126,7 @@ const createAuthHeader = (credentials: GerritCredentials): string => {
 const makeRequest = <T = unknown>(
   url: string,
   authHeader: string,
-  method: 'GET' | 'POST' = 'GET',
+  method: 'GET' | 'POST' | 'PUT' | 'DELETE' = 'GET',
   body?: unknown,
   schema?: Schema.Schema<T>,
 ): Effect.Effect<T, ApiError> =>
@@ -155,12 +154,7 @@ const makeRequest = <T = unknown>(
         try: () => response.text(),
         catch: () => 'Unknown error',
       }).pipe(Effect.orElseSucceed(() => 'Unknown error'))
-      yield* Effect.fail(
-        new ApiError({
-          message: errorText,
-          status: response.status,
-        }),
-      )
+      yield* Effect.fail(new ApiError({ message: errorText, status: response.status }))
     }
 
     const text = yield* Effect.tryPromise({
@@ -168,13 +162,8 @@ const makeRequest = <T = unknown>(
       catch: () => new ApiError({ message: 'Failed to read response data' }),
     })
 
-    // Gerrit returns JSON with )]}' prefix for security
     const cleanJson = text.replace(/^\)\]\}'\n?/, '')
-
-    if (!cleanJson.trim()) {
-      // Empty response - return empty object for endpoints that expect void
-      return {} as T
-    }
+    if (!cleanJson.trim()) return {} as T
 
     const parsed = yield* Effect.try({
       try: () => JSON.parse(cleanJson),
@@ -186,8 +175,6 @@ const makeRequest = <T = unknown>(
         Effect.mapError(() => new ApiError({ message: 'Invalid response format from server' })),
       )
     }
-
-    // When no schema is provided, the caller expects void or doesn't care about the response
     return parsed
   })
 
@@ -201,16 +188,13 @@ export const GerritApiServiceLive: Layer.Layer<GerritApiService, never, ConfigSe
         const credentials = yield* configService.getCredentials.pipe(
           Effect.mapError(() => new ApiError({ message: 'Failed to get credentials' })),
         )
-        // Ensure host doesn't have trailing slash
-        const normalizedCredentials = {
-          ...credentials,
-          host: credentials.host.replace(/\/$/, ''),
+        const normalizedCredentials = { ...credentials, host: credentials.host.replace(/\/$/, '') }
+        return {
+          credentials: normalizedCredentials,
+          authHeader: createAuthHeader(normalizedCredentials),
         }
-        const authHeader = createAuthHeader(normalizedCredentials)
-        return { credentials: normalizedCredentials, authHeader }
       })
 
-      // Helper to normalize and validate change identifier
       const normalizeAndValidate = (changeId: string): Effect.Effect<string, ApiError> =>
         Effect.try({
           try: () => normalizeChangeIdentifier(changeId),
@@ -231,9 +215,7 @@ export const GerritApiServiceLive: Layer.Layer<GerritApiService, never, ConfigSe
       const listChanges = (query = 'is:open') =>
         Effect.gen(function* () {
           const { credentials, authHeader } = yield* getCredentialsAndAuth
-          const encodedQuery = encodeURIComponent(query)
-          // Add additional options to get detailed information
-          const url = `${credentials.host}/a/changes/?q=${encodedQuery}&o=LABELS&o=DETAILED_LABELS&o=DETAILED_ACCOUNTS&o=SUBMITTABLE`
+          const url = `${credentials.host}/a/changes/?q=${encodeURIComponent(query)}&o=LABELS&o=DETAILED_LABELS&o=DETAILED_ACCOUNTS&o=SUBMITTABLE`
           return yield* makeRequest(url, authHeader, 'GET', undefined, Schema.Array(ChangeInfo))
         })
 
@@ -241,10 +223,7 @@ export const GerritApiServiceLive: Layer.Layer<GerritApiService, never, ConfigSe
         Effect.gen(function* () {
           const { credentials, authHeader } = yield* getCredentialsAndAuth
           let url = `${credentials.host}/a/projects/`
-          if (options?.pattern) {
-            url += `?p=${encodeURIComponent(options.pattern)}`
-          }
-          // Gerrit returns projects as a Record, need to convert to array
+          if (options?.pattern) url += `?p=${encodeURIComponent(options.pattern)}`
           const projectsRecord = yield* makeRequest(
             url,
             authHeader,
@@ -252,7 +231,6 @@ export const GerritApiServiceLive: Layer.Layer<GerritApiService, never, ConfigSe
             undefined,
             Schema.Record({ key: Schema.String, value: ProjectInfo }),
           )
-          // Convert Record to Array and sort alphabetically by name
           return Object.values(projectsRecord).sort((a, b) => a.name.localeCompare(b.name))
         })
 
@@ -306,7 +284,6 @@ export const GerritApiServiceLive: Layer.Layer<GerritApiService, never, ConfigSe
         return true
       }).pipe(
         Effect.catchAll((error) => {
-          // Log the actual error for debugging
           if (process.env.DEBUG) {
             console.error('Connection error:', error)
           }
@@ -373,15 +350,8 @@ export const GerritApiServiceLive: Layer.Layer<GerritApiService, never, ConfigSe
               try: () => response.text(),
               catch: () => 'Unknown error',
             }).pipe(Effect.orElseSucceed(() => 'Unknown error'))
-
-            yield* Effect.fail(
-              new ApiError({
-                message: errorText,
-                status: response.status,
-              }),
-            )
+            yield* Effect.fail(new ApiError({ message: errorText, status: response.status }))
           }
-
           const base64Content = yield* Effect.tryPromise({
             try: () => response.text(),
             catch: () => new ApiError({ message: 'Failed to read response data' }),
@@ -414,15 +384,8 @@ export const GerritApiServiceLive: Layer.Layer<GerritApiService, never, ConfigSe
               try: () => response.text(),
               catch: () => 'Unknown error',
             }).pipe(Effect.orElseSucceed(() => 'Unknown error'))
-
-            yield* Effect.fail(
-              new ApiError({
-                message: errorText,
-                status: response.status,
-              }),
-            )
+            yield* Effect.fail(new ApiError({ message: errorText, status: response.status }))
           }
-
           const base64Patch = yield* Effect.tryPromise({
             try: () => response.text(),
             catch: () => new ApiError({ message: 'Failed to read response data' }),
@@ -546,7 +509,6 @@ export const GerritApiServiceLive: Layer.Layer<GerritApiService, never, ConfigSe
           const url = `${credentials.host}/a/changes/${encodeURIComponent(normalized)}?o=MESSAGES`
           const response = yield* makeRequest(url, authHeader, 'GET')
 
-          // Extract messages from the change response with runtime validation
           const changeResponse = yield* Schema.decodeUnknown(
             Schema.Struct({
               messages: Schema.optional(Schema.Array(MessageInfo)),
@@ -616,7 +578,6 @@ export const GerritApiServiceLive: Layer.Layer<GerritApiService, never, ConfigSe
             url += `?${params.join('&')}`
           }
 
-          // Gerrit returns groups as a Record, need to convert to array
           const groupsRecord = yield* makeRequest(
             url,
             authHeader,
@@ -624,12 +585,9 @@ export const GerritApiServiceLive: Layer.Layer<GerritApiService, never, ConfigSe
             undefined,
             Schema.Record({ key: Schema.String, value: GroupInfo }),
           )
-          // Convert Record to Array and sort alphabetically by name
-          return Object.values(groupsRecord).sort((a, b) => {
-            const aName = a.name || a.id
-            const bName = b.name || b.id
-            return aName.localeCompare(bName)
-          })
+          return Object.values(groupsRecord).sort((a, b) =>
+            (a.name || a.id).localeCompare(b.name || b.id),
+          )
         })
 
       const getGroup = (groupId: string) =>
@@ -661,12 +619,54 @@ export const GerritApiServiceLive: Layer.Layer<GerritApiService, never, ConfigSe
         Effect.gen(function* () {
           const { credentials, authHeader } = yield* getCredentialsAndAuth
           const normalized = yield* normalizeAndValidate(changeId)
-          // Use POST to /delete endpoint to support request body with notify option
           const url = `${credentials.host}/a/changes/${encodeURIComponent(normalized)}/reviewers/${encodeURIComponent(accountId)}/delete`
           const body = options?.notify ? { notify: options.notify } : {}
           yield* makeRequest(url, authHeader, 'POST', body)
         })
 
+      const getTopicUrl = (host: string, changeId: string): string =>
+        `${host}/a/changes/${encodeURIComponent(changeId)}/topic`
+
+      const getTopic = (changeId: string) =>
+        Effect.gen(function* () {
+          const { credentials, authHeader } = yield* getCredentialsAndAuth
+          const normalized = yield* normalizeAndValidate(changeId)
+          return yield* makeRequest(
+            getTopicUrl(credentials.host, normalized),
+            authHeader,
+            'GET',
+            undefined,
+            Schema.String,
+          ).pipe(
+            Effect.map((t) => t.replace(/^"|"$/g, '') || null),
+            Effect.catchIf(
+              (e) => e instanceof ApiError && e.status === 404,
+              () => Effect.succeed(null),
+            ),
+          )
+        })
+
+      const setTopic = (changeId: string, topic: string) =>
+        Effect.gen(function* () {
+          const { credentials, authHeader } = yield* getCredentialsAndAuth
+          const normalized = yield* normalizeAndValidate(changeId)
+          const result = yield* makeRequest(
+            getTopicUrl(credentials.host, normalized),
+            authHeader,
+            'PUT',
+            { topic },
+            Schema.String,
+          )
+          return result.replace(/^"|"$/g, '')
+        })
+
+      const deleteTopic = (changeId: string) =>
+        Effect.gen(function* () {
+          const { credentials, authHeader } = yield* getCredentialsAndAuth
+          const normalized = yield* normalizeAndValidate(changeId)
+          yield* makeRequest(getTopicUrl(credentials.host, normalized), authHeader, 'DELETE')
+        })
+
       return {
         getChange,
         listChanges,
@@ -691,6 +691,9 @@ export const GerritApiServiceLive: Layer.Layer<GerritApiService, never, ConfigSe
         getGroupDetail,
         getGroupMembers,
         removeReviewer,
+        getTopic,
+        setTopic,
+        deleteTopic,
       }
     }),
   )

package/src/cli/commands/comment.ts

@@ -3,6 +3,24 @@ import { Effect, pipe } from 'effect'
 import { type ApiError, GerritApiService } from '@/api/gerrit'
 import type { ChangeInfo, ReviewInput } from '@/schemas/gerrit'
 
+export const COMMENT_HELP_TEXT = `
+Examples:
+  # Post a general comment on a change
+  $ ger comment 12345 -m "Looks good to me!"
+
+  # Post a comment using piped input
+  $ echo "This is a comment from stdin!" | ger comment 12345
+
+  # Post a line-specific comment
+  $ ger comment 12345 --file src/main.js --line 42 -m "Consider using const here"
+
+  # Post multiple comments using batch mode
+  $ echo '{"message": "Review complete", "comments": [
+      {"file": "src/main.js", "line": 10, "message": "Good refactor"}
+    ]}' | ger comment 12345 --batch
+
+Note: Line numbers refer to the NEW version of the file, not diff line numbers.`
+
 interface CommentOptions {
   message?: string
   xml?: boolean

package/src/cli/commands/install-hook.ts

@@ -0,0 +1,59 @@
+import { Effect, Console } from 'effect'
+import chalk from 'chalk'
+import {
+  CommitHookService,
+  type CommitHookServiceImpl,
+  type HookInstallError,
+  type NotGitRepoError,
+} from '@/services/commit-hook'
+import { type ConfigError, type ConfigServiceImpl } from '@/services/config'
+
+export interface InstallHookOptions {
+  force?: boolean
+  xml?: boolean
+}
+
+export type InstallHookErrors = ConfigError | HookInstallError | NotGitRepoError
+
+export const installHookCommand = (
+  options: InstallHookOptions,
+): Effect.Effect<void, InstallHookErrors, CommitHookServiceImpl | ConfigServiceImpl> =>
+  Effect.gen(function* () {
+    const commitHookService = yield* CommitHookService
+
+    // Check if hook already exists using service method
+    const hookExists = yield* commitHookService.hasHook()
+
+    if (hookExists && !options.force) {
+      if (options.xml) {
+        yield* Console.log('<?xml version="1.0" encoding="UTF-8"?>')
+        yield* Console.log('<install_hook_result>')
+        yield* Console.log('  <status>skipped</status>')
+        yield* Console.log('  <message><![CDATA[commit-msg hook already installed]]></message>')
+        yield* Console.log('  <hint><![CDATA[Use --force to overwrite]]></hint>')
+        yield* Console.log('</install_hook_result>')
+      } else {
+        yield* Console.log(chalk.yellow('commit-msg hook already installed'))
+        yield* Console.log(chalk.dim('Use --force to overwrite'))
+      }
+      return
+    }
+
+    if (hookExists && options.force) {
+      if (!options.xml) {
+        yield* Console.log(chalk.yellow('Overwriting existing commit-msg hook...'))
+      }
+    }
+
+    // Install the hook (service logs progress messages in non-XML mode)
+    yield* commitHookService.installHook()
+
+    // Only output XML here - service already logs success message for non-XML mode
+    if (options.xml) {
+      yield* Console.log('<?xml version="1.0" encoding="UTF-8"?>')
+      yield* Console.log('<install_hook_result>')
+      yield* Console.log('  <status>success</status>')
+      yield* Console.log('  <message><![CDATA[commit-msg hook installed successfully]]></message>')
+      yield* Console.log('</install_hook_result>')
+    }
+  })