@aaronshaf/ger 2.0.1 → 2.0.3

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/adr/0023-show-reviewer-list.md

@@ -0,0 +1,42 @@
+# ADR 0023: Surface Reviewers and CCs in `ger show`
+
+## Status
+
+Accepted
+
+## Context
+
+`ger` supports reviewer management (`add-reviewer`, `remove-reviewer`) but did not expose a reliable way to view current reviewers for a change in one command.
+
+This created a workflow gap:
+
+- Users could mutate reviewer state but not inspect it from the CLI.
+- `show` already served as the canonical "single change detail" command and was the best place to surface reviewer assignments.
+
+## Decision
+
+Add reviewer visibility to `ger show` by:
+
+1. Keeping `getChange` lightweight and using a `listChanges` fallback (with detailed account/label options) when reviewer state is not present in the base change response.
+2. Extending `ChangeInfo` schema with Gerrit reviewer state maps (`REVIEWER`, `CC`, `REMOVED`).
+3. Rendering reviewers and CCs in all `show` output formats (pretty, JSON, XML).
+
+## Rationale
+
+- **Single source of truth**: `show` remains the canonical command for full change context.
+- **No new command surface**: avoids adding a narrowly scoped `list-reviewers` command.
+- **Automation-friendly**: JSON/XML consumers can parse reviewer state without scraping text output.
+- **Backward compatible**: reviewer fields are optional and do not break servers or older data shapes.
+
+## Consequences
+
+### Positive
+
+- Users can verify reviewer assignment directly after add/remove operations.
+- Better parity between mutation commands and read visibility.
+- More complete machine-readable change payloads.
+
+### Negative
+
+- Extra `listChanges` request when reviewer data is absent from `getChange`.
+- Additional schema/output maintenance for reviewer state rendering.

package/docs/adr/README.md

@@ -28,3 +28,4 @@ Records of significant architectural decisions with context and rationale. Each
 | [0020](0020-code-coverage-enforcement.md) | 80% coverage threshold in pre-commit |
 | [0021](0021-typescript-isolated-declarations.md) | Explicit return types on exports |
 | [0022](0022-biome-oxlint-tooling.md) | Biome formatter + oxlint linter |
+| [0023](0023-show-reviewer-list.md) | Surface reviewers and CCs in `ger show` |

package/docs/prd/commands.md

@@ -23,11 +23,13 @@ ger show              # Auto-detect from HEAD
 
 **Output includes:**
 - Change metadata (number, project, branch, status)
-- Owner and reviewer information
+- Owner, reviewers, and CC information
 - Submit requirements
 - Full diff
 - All comments with context
 
+Reviewer listing for a specific change is provided by `show` (there is no separate `list-reviewers` command).
+
 ### diff
 
 Get change diff in various formats.
@@ -129,6 +131,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 +421,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/docs/prd/data-model.md

@@ -14,25 +14,36 @@ const ChangeInfo = Schema.Struct({
   _number: Schema.Number,         // Numeric change ID
   project: Schema.String,         // Project name
   branch: Schema.String,          // Target branch
+  change_id: Schema.String,       // Gerrit Change-Id
   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,
+  created: Schema.optional(Schema.String),
+  updated: Schema.optional(Schema.String),
+  owner: Schema.optional(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),
+  reviewers: Schema.optional(ReviewerStateMap),
+  submittable: Schema.optional(Schema.Boolean),
+  work_in_progress: Schema.optional(Schema.Boolean),
   insertions: Schema.optional(Schema.Number),
   deletions: Schema.optional(Schema.Number),
 })
 ```
 
+### ReviewerStateMap
+
+Reviewer assignments grouped by Gerrit reviewer state.
+
+```typescript
+const ReviewerStateMap = Schema.Struct({
+  REVIEWER: Schema.optional(Schema.Array(AccountInfo)),
+  CC: Schema.optional(Schema.Array(AccountInfo)),
+  REMOVED: Schema.optional(Schema.Array(AccountInfo)),
+})
+```
+
 ### AccountInfo
 
 User account information.

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.3",
   "description": "Gerrit CLI and SDK - A modern CLI tool and TypeScript SDK for Gerrit Code Review, built with Effect-TS",
   "keywords": [
     "gerrit",