@aaronshaf/ger 0.2.4 → 0.3.1

package/CLAUDE.md

@@ -25,10 +25,10 @@
 ### Testing & Coverage
 - **ENFORCE** minimum 80% code coverage
 - **RUN** all tests in pre-commit and pre-push hooks
-- **USE** Bun's native fetch mocking for all HTTP requests
+- **USE** MSW (Mock Service Worker) for all HTTP request mocking
 - **REQUIRE** meaningful integration tests for all commands that simulate full workflows
 - **IMPLEMENT** both unit tests and integration tests for every command modification/addition
-- **ENSURE** integration tests use realistic Bun HTTP mocks that match Gerrit API responses
+- **ENSURE** integration tests use realistic MSW handlers that match Gerrit API responses
 - **EXCLUDE** generated code and tmp/ from coverage
 
 ### Security
@@ -56,7 +56,7 @@
 ### Testing Requirements for Commands
 - **UNIT TESTS**: Test individual functions, schemas, and utilities
 - **INTEGRATION TESTS**: Test complete command flows with mocked HTTP requests
-- **HTTP MOCKING**: Use `global.fetch = mock(...)` pattern with Bun's native mocking
+- **HTTP MOCKING**: Use MSW handlers with http.get/http.post patterns for mocking
 - **SCHEMA VALIDATION**: Ensure mocks return data that validates against Effect Schemas
 - **COMMAND COVERAGE**: Every command must have integration tests covering:
   - Happy path execution

package/README.md

@@ -55,6 +55,14 @@ ger diff 12345
 # Extract URLs from messages (e.g., Jenkins build links)
 ger extract-url "build-summary-report" | tail -1
 
+# Check CI build status (parses build messages)
+ger build-status 12345  # Returns: pending, running, success, failure, or not_found
+ger build-status        # Auto-detects from HEAD commit
+
+# Watch build status until completion (like gh run watch)
+ger build-status 12345 --watch
+ger build-status --watch --exit-status && deploy.sh
+
 # AI-powered code review (requires claude, llm, or opencode CLI)
 ger review 12345
 ger review 12345 --dry-run  # Preview without posting
@@ -249,6 +257,85 @@ ger extract-url "github.com" --include-comments
 ger extract-url "job/[^/]+/job/[^/]+/\d+/$" --regex
 ```
 
+### Build Status
+
+Check the CI build status of a change by parsing Gerrit messages for build events and verification results:
+
+#### Single Check (Snapshot)
+```bash
+# Check build status for a specific change
+ger build-status 12345
+# Output: {"state":"success"}
+
+# Auto-detect change from HEAD commit
+ger build-status
+
+# Use in scripts with jq
+ger build-status | jq -r '.state'
+```
+
+#### Watch Mode (Poll Until Completion)
+Like `gh run watch`, you can poll the build status until it reaches a terminal state:
+
+```bash
+# Watch until completion (outputs JSON on each poll)
+ger build-status 12345 --watch
+# Output:
+# {"state":"pending"}
+# {"state":"running"}
+# {"state":"running"}
+# {"state":"success"}
+
+# Auto-detect from HEAD commit
+ger build-status --watch
+
+# Custom polling interval (check every 5 seconds, default: 10)
+ger build-status --watch --interval 5
+
+# Custom timeout (60 minutes, default: 30 minutes)
+ger build-status --watch --timeout 3600
+
+# Exit with code 1 on build failure (for CI/CD pipelines)
+ger build-status --watch --exit-status && deploy.sh
+
+# Trigger notification when done (like gh run watch pattern)
+ger build-status --watch && notify-send 'Build is done!'
+
+# Extract final state in scripts
+ger build-status --watch | tail -1 | jq -r '.state'
+```
+
+#### Output format (JSON):
+```json
+{"state": "success"}
+```
+
+#### Build states:
+- **`pending`**: No "Build Started" message found yet
+- **`running`**: "Build Started" found, but no verification result yet
+- **`success`**: Verified +1 after most recent "Build Started"
+- **`failure`**: Verified -1 after most recent "Build Started"
+- **`not_found`**: Change does not exist
+
+#### Exit codes:
+- **`0`**: Default for all states (like `gh run watch`)
+- **`1`**: Only when `--exit-status` flag is used AND build fails
+- **`2`**: Timeout reached in watch mode
+- **`3`**: API/network errors
+
+#### How it works:
+1. Fetches all messages for the change
+2. Finds the most recent "Build Started" message
+3. Checks for "Verified +1" or "Verified -1" messages after the build started
+4. Returns the appropriate state
+5. In watch mode: polls every N seconds until terminal state or timeout
+
+#### Use cases:
+- **CI/CD integration**: Wait for builds before proceeding with deployment
+- **Automation**: Trigger actions based on build results
+- **Scripting**: Check build status in shell scripts
+- **Monitoring**: Poll build status for long-running builds with watch mode
+
 ### Diff
 ```bash
 # Full diff

package/package.json

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

package/src/cli/commands/build-status.ts

@@ -0,0 +1,238 @@
+import { Effect, Schema } from 'effect'
+import { type ApiError, GerritApiService } from '@/api/gerrit'
+import type { MessageInfo } from '@/schemas/gerrit'
+import { getChangeIdFromHead, GitError, NoChangeIdError } from '@/utils/git-commit'
+
+// Export types for external use
+export type BuildState = 'pending' | 'running' | 'success' | 'failure' | 'not_found'
+
+// Watch options (matches gh run watch pattern)
+export type WatchOptions = {
+  readonly watch: boolean
+  readonly interval: number // seconds
+  readonly timeout: number // seconds
+  readonly exitStatus: boolean
+}
+
+// Timeout error for watch mode
+export class TimeoutError extends Error {
+  readonly _tag = 'TimeoutError'
+  constructor(message: string) {
+    super(message)
+    this.name = 'TimeoutError'
+  }
+}
+
+// Effect Schema for BuildStatus (follows project patterns)
+export const BuildStatus: Schema.Schema<{
+  readonly state: 'pending' | 'running' | 'success' | 'failure' | 'not_found'
+}> = Schema.Struct({
+  state: Schema.Literal('pending', 'running', 'success', 'failure', 'not_found'),
+})
+export type BuildStatus = Schema.Schema.Type<typeof BuildStatus>
+
+// Message patterns for precise matching
+const BUILD_STARTED_PATTERN = /Build\s+Started/i
+const VERIFIED_PLUS_PATTERN = /Verified\s*[+]\s*1/
+const VERIFIED_MINUS_PATTERN = /Verified\s*[-]\s*1/
+
+/**
+ * Parse messages to determine build status based on "Build Started" and verification messages
+ */
+const parseBuildStatus = (messages: readonly MessageInfo[]): BuildStatus => {
+  // Empty messages means change exists but has no activity yet - return pending
+  if (messages.length === 0) {
+    return { state: 'pending' }
+  }
+
+  // Find the most recent "Build Started" message
+  let lastBuildDate: string | null = null
+  for (const msg of messages) {
+    if (BUILD_STARTED_PATTERN.test(msg.message)) {
+      lastBuildDate = msg.date
+    }
+  }
+
+  // If no build has started, state is "pending"
+  if (!lastBuildDate) {
+    return { state: 'pending' }
+  }
+
+  // Check for verification messages after the build started
+  for (const msg of messages) {
+    const date = msg.date
+    // Gerrit timestamps are ISO 8601 strings (lexicographically sortable)
+    if (date <= lastBuildDate) continue
+
+    if (VERIFIED_PLUS_PATTERN.test(msg.message)) {
+      return { state: 'success' }
+    } else if (VERIFIED_MINUS_PATTERN.test(msg.message)) {
+      return { state: 'failure' }
+    }
+  }
+
+  // Build started but no verification yet, state is "running"
+  return { state: 'running' }
+}
+
+/**
+ * Get messages for a change
+ */
+const getMessagesForChange = (
+  changeId: string,
+): Effect.Effect<readonly MessageInfo[], ApiError, GerritApiService> =>
+  Effect.gen(function* () {
+    const gerritApi = yield* GerritApiService
+    const messages = yield* gerritApi.getMessages(changeId)
+    return messages
+  })
+
+/**
+ * Poll build status until terminal state or timeout
+ * Outputs JSON status on each iteration (mimics gh run watch)
+ */
+const pollBuildStatus = (
+  changeId: string,
+  options: WatchOptions,
+): Effect.Effect<BuildStatus, ApiError | TimeoutError, GerritApiService> =>
+  Effect.gen(function* () {
+    const startTime = Date.now()
+    const timeoutMs = options.timeout * 1000
+
+    // Initial message to stderr
+    yield* Effect.sync(() => {
+      console.error(
+        `Watching build status (polling every ${options.interval}s, timeout: ${options.timeout}s)...`,
+      )
+    })
+
+    while (true) {
+      // Check timeout
+      const elapsed = Date.now() - startTime
+      if (elapsed > timeoutMs) {
+        yield* Effect.sync(() => {
+          console.error(`Timeout: Build status check exceeded ${options.timeout}s`)
+        })
+        yield* Effect.fail(
+          new TimeoutError(`Build status check timed out after ${options.timeout}s`),
+        )
+      }
+
+      // Fetch and parse status
+      const messages = yield* getMessagesForChange(changeId)
+      const status = parseBuildStatus(messages)
+
+      // Check timeout again after API call (in case it took longer than expected)
+      const elapsedAfterFetch = Date.now() - startTime
+      if (elapsedAfterFetch > timeoutMs) {
+        yield* Effect.sync(() => {
+          console.error(`Timeout: Build status check exceeded ${options.timeout}s`)
+        })
+        yield* Effect.fail(
+          new TimeoutError(`Build status check timed out after ${options.timeout}s`),
+        )
+      }
+
+      // Output current status to stdout (JSON, like single-check mode)
+      yield* Effect.sync(() => {
+        process.stdout.write(JSON.stringify(status) + '\n')
+      })
+
+      // Terminal states - return immediately
+      if (
+        status.state === 'success' ||
+        status.state === 'failure' ||
+        status.state === 'not_found'
+      ) {
+        yield* Effect.sync(() => {
+          console.error(`Build completed with status: ${status.state}`)
+        })
+        return status
+      }
+
+      // Non-terminal states - log progress and wait
+      const elapsedSeconds = Math.floor(elapsed / 1000)
+      yield* Effect.sync(() => {
+        console.error(`[${elapsedSeconds}s elapsed] Build status: ${status.state}`)
+      })
+
+      // Sleep for interval duration
+      yield* Effect.sleep(options.interval * 1000)
+    }
+  })
+
+/**
+ * Build status command with optional watch mode (mimics gh run watch)
+ */
+export const buildStatusCommand = (
+  changeId: string | undefined,
+  options: Partial<WatchOptions> = {},
+): Effect.Effect<
+  void,
+  ApiError | Error | GitError | NoChangeIdError | TimeoutError,
+  GerritApiService
+> =>
+  Effect.gen(function* () {
+    // Auto-detect Change-ID from HEAD commit if not provided
+    const resolvedChangeId = changeId || (yield* getChangeIdFromHead())
+
+    // Set defaults (matching gh run watch patterns)
+    const watchOpts: WatchOptions = {
+      watch: options.watch ?? false,
+      interval: Math.max(1, options.interval ?? 10), // Min 1 second
+      timeout: Math.max(1, options.timeout ?? 1800), // Min 1 second, default 30 minutes
+      exitStatus: options.exitStatus ?? false,
+    }
+
+    let status: BuildStatus
+
+    if (watchOpts.watch) {
+      // Polling mode - outputs JSON on each iteration
+      status = yield* pollBuildStatus(resolvedChangeId, watchOpts)
+    } else {
+      // Single check mode (existing behavior)
+      const messages = yield* getMessagesForChange(resolvedChangeId)
+      status = parseBuildStatus(messages)
+
+      // Output JSON to stdout
+      yield* Effect.sync(() => {
+        process.stdout.write(JSON.stringify(status) + '\n')
+      })
+    }
+
+    // Handle exit codes (only non-zero when explicitly requested)
+    if (watchOpts.exitStatus && status.state === 'failure') {
+      yield* Effect.sync(() => process.exit(1))
+    }
+
+    // Default: exit 0 for all states (success, failure, pending, etc.)
+  }).pipe(
+    Effect.catchAll((error) => {
+      // Timeout error
+      if (error instanceof TimeoutError) {
+        return Effect.sync(() => {
+          console.error(`Error: ${error.message}`)
+          process.exit(2)
+        })
+      }
+
+      // 404 - change not found
+      if (error && typeof error === 'object' && 'status' in error && error.status === 404) {
+        const status: BuildStatus = { state: 'not_found' }
+        return Effect.sync(() => {
+          process.stdout.write(JSON.stringify(status) + '\n')
+        })
+      }
+
+      // Other errors - exit 3
+      const errorMessage =
+        error instanceof GitError || error instanceof NoChangeIdError || error instanceof Error
+          ? error.message
+          : String(error)
+
+      return Effect.sync(() => {
+        console.error(`Error: ${errorMessage}`)
+        process.exit(3)
+      })
+    }),
+  )

package/src/cli/index.ts

@@ -31,6 +31,7 @@ import { ConfigServiceLive } from '@/services/config'
 import { ReviewStrategyServiceLive } from '@/services/review-strategy'
 import { GitWorktreeServiceLive } from '@/services/git-worktree'
 import { abandonCommand } from './commands/abandon'
+import { buildStatusCommand } from './commands/build-status'
 import { commentCommand } from './commands/comment'
 import { commentsCommand } from './commands/comments'
 import { diffCommand } from './commands/diff'
@@ -419,6 +420,85 @@ Note: When no change-id is provided, it will be automatically extracted from the
     }
   })
 
+// build-status command
+program
+  .command('build-status [change-id]')
+  .description(
+    'Check build status from Gerrit messages (auto-detects from HEAD commit if not specified)',
+  )
+  .option('--watch', 'Watch build status until completion (mimics gh run watch)')
+  .option('-i, --interval <seconds>', 'Refresh interval in seconds (default: 10)', '10')
+  .option('--timeout <seconds>', 'Maximum wait time in seconds (default: 1800 / 30min)', '1800')
+  .option('--exit-status', 'Exit with non-zero status if build fails')
+  .addHelpText(
+    'after',
+    `
+This command parses Gerrit change messages to determine build status.
+It looks for "Build Started" messages and subsequent verification labels.
+
+Output is JSON with a "state" field that can be:
+  - pending: No build has started yet
+  - running: Build started but no verification yet
+  - success: Build completed with Verified+1
+  - failure: Build completed with Verified-1
+  - not_found: Change does not exist
+
+Exit codes:
+  - 0: Default for all states (like gh run watch)
+  - 1: Only when --exit-status is used AND build fails
+  - 2: Timeout reached in watch mode
+  - 3: API/network errors
+
+Examples:
+  # Single check (current behavior)
+  $ ger build-status 392385
+  {"state":"success"}
+
+  # Watch until completion (outputs JSON on each poll)
+  $ ger build-status 392385 --watch
+  {"state":"pending"}
+  {"state":"running"}
+  {"state":"running"}
+  {"state":"success"}
+
+  # Watch with custom interval (check every 5 seconds)
+  $ ger build-status --watch --interval 5
+
+  # Watch with custom timeout (60 minutes)
+  $ ger build-status --watch --timeout 3600
+
+  # Exit with code 1 on failure (for CI/CD pipelines)
+  $ ger build-status --watch --exit-status && deploy.sh
+
+  # Trigger notification when done (like gh run watch pattern)
+  $ ger build-status --watch && notify-send 'Build is done!'
+
+  # Parse final state in scripts
+  $ ger build-status --watch | tail -1 | jq -r '.state'
+  success
+
+Note: When no change-id is provided, it will be automatically extracted from the
+      Change-ID footer in your HEAD commit.`,
+  )
+  .action(async (changeId, cmdOptions) => {
+    try {
+      const effect = buildStatusCommand(changeId, {
+        watch: cmdOptions.watch,
+        interval: Number.parseInt(cmdOptions.interval, 10),
+        timeout: Number.parseInt(cmdOptions.timeout, 10),
+        exitStatus: cmdOptions.exitStatus,
+      }).pipe(Effect.provide(GerritApiServiceLive), Effect.provide(ConfigServiceLive))
+      await Effect.runPromise(effect)
+    } catch (error) {
+      // Errors are handled within the command itself
+      // This catch is just for any unexpected errors
+      if (error instanceof Error && error.message !== 'Process exited') {
+        console.error('✗ Unexpected error:', error.message)
+        process.exit(3)
+      }
+    }
+  })
+
 // extract-url command
 program
   .command('extract-url <pattern> [change-id]')