bitbucket-gemini-action 1.0.0

package/src/modes/agent/index.ts

@@ -0,0 +1,119 @@
+/**
+ * Agent Mode Implementation
+ * Automated execution with explicit prompt
+ */
+
+import type {
+  Mode,
+  ModeOptions,
+  ModeResult,
+  TriggerCheckResult,
+} from "../types.js";
+import type { ParsedBitbucketContext } from "../../bitbucket/types.js";
+import { AGENT_MODE_SYSTEM_PROMPT } from "../../gemini/prompts.js";
+import { codeReviewTools } from "../../gemini/tools.js";
+
+export class AgentMode implements Mode {
+  name = "agent" as const;
+  description = "Automated execution with explicit prompt from pipeline";
+
+  shouldTrigger(
+    _context: ParsedBitbucketContext,
+    options: { triggerPhrase: string; prompt?: string }
+  ): TriggerCheckResult {
+    // Agent mode triggers when explicit prompt is provided
+    if (!options.prompt) {
+      return {
+        shouldTrigger: false,
+        reason: "No explicit prompt provided",
+      };
+    }
+
+    return {
+      shouldTrigger: true,
+      userMessage: options.prompt,
+    };
+  }
+
+  async prepare(options: ModeOptions): Promise<ModeResult> {
+    const { context, client, prompt } = options;
+
+    try {
+      if (!prompt) {
+        return {
+          success: false,
+          modeContext: {
+            prompt: "",
+            systemPrompt: "",
+            tools: [],
+          },
+          error: "Agent mode requires an explicit prompt",
+        };
+      }
+
+      // Optionally create tracking comment for visibility
+      let trackingCommentId: number | undefined;
+      if (options.createTrackingComment && context.entityNumber) {
+        const trackingComment = await client.createPullRequestComment(
+          context.workspace,
+          context.repoSlug,
+          context.entityNumber,
+          this.getInitialTrackingCommentContent(prompt)
+        );
+        trackingCommentId = trackingComment.id;
+      }
+
+      return {
+        success: true,
+        modeContext: {
+          prompt,
+          systemPrompt: this.getSystemPrompt(context),
+          tools: this.getAllowedTools(),
+          trackingCommentId,
+        },
+        trackingCommentId,
+      };
+    } catch (error) {
+      return {
+        success: false,
+        modeContext: {
+          prompt: "",
+          systemPrompt: "",
+          tools: [],
+        },
+        error: error instanceof Error ? error.message : "Unknown error",
+      };
+    }
+  }
+
+  getSystemPrompt(_context: ParsedBitbucketContext): string {
+    return AGENT_MODE_SYSTEM_PROMPT;
+  }
+
+  getAllowedTools(): string[] {
+    return codeReviewTools.map((t) => t.name);
+  }
+
+  shouldCreateTrackingComment(): boolean {
+    // Agent mode doesn't require tracking comment by default
+    return false;
+  }
+
+  private getInitialTrackingCommentContent(prompt: string): string {
+    // Truncate long prompts for display
+    const displayPrompt =
+      prompt.length > 200 ? `${prompt.substring(0, 200)}...` : prompt;
+
+    return `## 🤖 Gemini Agent Task
+
+⏳ **Status**: Executing automated task...
+
+**Task**:
+> ${displayPrompt}
+
+---
+_This comment will be updated with the results._`;
+  }
+}
+
+export const agentMode = new AgentMode();

package/src/modes/registry.ts

@@ -0,0 +1,118 @@
+/**
+ * Mode Registry
+ * Central registry for all execution modes
+ */
+
+import type { Mode, ModeName, ModeRegistry } from "./types.js";
+import type { ParsedBitbucketContext } from "../bitbucket/types.js";
+import { tagMode } from "./tag/index.js";
+import { agentMode } from "./agent/index.js";
+
+/**
+ * Registry of all available modes
+ */
+export const modeRegistry: ModeRegistry = {
+  tag: tagMode,
+  agent: agentMode,
+};
+
+/**
+ * Get a mode by name
+ */
+export function getMode(name: ModeName): Mode {
+  const mode = modeRegistry[name];
+  if (!mode) {
+    throw new Error(`Unknown mode: ${name}`);
+  }
+  return mode;
+}
+
+/**
+ * Auto-detect the appropriate mode based on context
+ */
+export function detectMode(
+  context: ParsedBitbucketContext,
+  options: {
+    triggerPhrase: string;
+    prompt?: string;
+    mode?: ModeName;
+  }
+): { mode: Mode; reason: string } {
+  // If mode is explicitly specified, use it
+  if (options.mode) {
+    return {
+      mode: getMode(options.mode),
+      reason: `Explicitly specified mode: ${options.mode}`,
+    };
+  }
+
+  // If explicit prompt is provided, use agent mode
+  if (options.prompt) {
+    return {
+      mode: agentMode,
+      reason: "Explicit prompt provided",
+    };
+  }
+
+  // Check if tag mode should trigger
+  const tagTrigger = tagMode.shouldTrigger(context, {
+    triggerPhrase: options.triggerPhrase,
+  });
+
+  if (tagTrigger.shouldTrigger) {
+    return {
+      mode: tagMode,
+      reason: "Trigger phrase detected in comment",
+    };
+  }
+
+  // Default to agent mode for automation events
+  if (
+    context.eventType === "manual" ||
+    context.eventType === "schedule"
+  ) {
+    return {
+      mode: agentMode,
+      reason: "Automation event (manual/schedule)",
+    };
+  }
+
+  // No mode triggered
+  return {
+    mode: tagMode,
+    reason: "Default mode (no specific trigger)",
+  };
+}
+
+/**
+ * Check if any mode should trigger for the given context
+ */
+export function shouldAnyModeTrigger(
+  context: ParsedBitbucketContext,
+  options: {
+    triggerPhrase: string;
+    prompt?: string;
+  }
+): boolean {
+  // Explicit prompt always triggers agent mode
+  if (options.prompt) {
+    return true;
+  }
+
+  // Check tag mode
+  const tagTrigger = tagMode.shouldTrigger(context, {
+    triggerPhrase: options.triggerPhrase,
+  });
+
+  return tagTrigger.shouldTrigger;
+}
+
+/**
+ * List all available modes
+ */
+export function listModes(): Array<{ name: ModeName; description: string }> {
+  return Object.values(modeRegistry).map((mode) => ({
+    name: mode.name,
+    description: mode.description,
+  }));
+}

package/src/modes/tag/index.ts

@@ -0,0 +1,172 @@
+/**
+ * Tag Mode Implementation
+ * Responds to @gemini mentions in PR comments
+ */
+
+import type {
+  Mode,
+  ModeOptions,
+  ModeResult,
+  TriggerCheckResult,
+} from "../types.js";
+import type { ParsedBitbucketContext } from "../../bitbucket/types.js";
+import { TAG_MODE_SYSTEM_PROMPT } from "../../gemini/prompts.js";
+import { codeReviewTools } from "../../gemini/tools.js";
+
+export class TagMode implements Mode {
+  name = "tag" as const;
+  description = "Responds to @gemini mentions in PR comments";
+
+  shouldTrigger(
+    context: ParsedBitbucketContext,
+    options: { triggerPhrase: string; prompt?: string }
+  ): TriggerCheckResult {
+    // Don't trigger if explicit prompt is provided (that's agent mode)
+    if (options.prompt) {
+      return {
+        shouldTrigger: false,
+        reason: "Explicit prompt provided, use agent mode",
+      };
+    }
+
+    // Check for comment events
+    if (
+      context.eventType !== "pullrequest:comment_created" &&
+      context.eventType !== "pullrequest:comment_updated"
+    ) {
+      return {
+        shouldTrigger: false,
+        reason: `Event type ${context.eventType} is not a comment event`,
+      };
+    }
+
+    // Check for trigger phrase in comment
+    const comment = context.comment;
+    if (!comment) {
+      return {
+        shouldTrigger: false,
+        reason: "No comment in context",
+      };
+    }
+
+    const triggerPhrase = options.triggerPhrase.toLowerCase();
+    const commentContent = comment.content.raw.toLowerCase();
+
+    if (!commentContent.includes(triggerPhrase)) {
+      return {
+        shouldTrigger: false,
+        reason: `Comment does not contain trigger phrase: ${options.triggerPhrase}`,
+      };
+    }
+
+    // Don't respond to our own comments (prevent infinite loops)
+    if (this.isOwnComment(comment.user.account_id)) {
+      return {
+        shouldTrigger: false,
+        reason: "Comment is from the bot itself",
+      };
+    }
+
+    // Extract user message (remove trigger phrase)
+    const userMessage = this.extractUserMessage(
+      comment.content.raw,
+      options.triggerPhrase
+    );
+
+    return {
+      shouldTrigger: true,
+      userMessage,
+      mentionAuthor: comment.user.display_name,
+    };
+  }
+
+  async prepare(options: ModeOptions): Promise<ModeResult> {
+    const { context, client, triggerPhrase } = options;
+
+    try {
+      // Verify trigger
+      const triggerCheck = this.shouldTrigger(context, { triggerPhrase });
+      if (!triggerCheck.shouldTrigger) {
+        return {
+          success: false,
+          modeContext: {
+            prompt: "",
+            systemPrompt: "",
+            tools: [],
+          },
+          error: triggerCheck.reason,
+        };
+      }
+
+      // Create tracking comment if enabled
+      let trackingCommentId: number | undefined;
+      if (options.createTrackingComment && context.entityNumber) {
+        const trackingComment = await client.createPullRequestComment(
+          context.workspace,
+          context.repoSlug,
+          context.entityNumber,
+          this.getInitialTrackingCommentContent()
+        );
+        trackingCommentId = trackingComment.id;
+      }
+
+      return {
+        success: true,
+        modeContext: {
+          prompt: triggerCheck.userMessage || "",
+          systemPrompt: this.getSystemPrompt(context),
+          tools: this.getAllowedTools(),
+          trackingCommentId,
+        },
+        trackingCommentId,
+      };
+    } catch (error) {
+      return {
+        success: false,
+        modeContext: {
+          prompt: "",
+          systemPrompt: "",
+          tools: [],
+        },
+        error: error instanceof Error ? error.message : "Unknown error",
+      };
+    }
+  }
+
+  getSystemPrompt(_context: ParsedBitbucketContext): string {
+    return TAG_MODE_SYSTEM_PROMPT;
+  }
+
+  getAllowedTools(): string[] {
+    return codeReviewTools.map((t) => t.name);
+  }
+
+  shouldCreateTrackingComment(): boolean {
+    return true;
+  }
+
+  private extractUserMessage(
+    commentContent: string,
+    triggerPhrase: string
+  ): string {
+    // Remove trigger phrase and clean up
+    const regex = new RegExp(triggerPhrase, "gi");
+    return commentContent.replace(regex, "").trim();
+  }
+
+  private isOwnComment(accountId: string): boolean {
+    const botAccountId = process.env.BOT_ACCOUNT_ID;
+    return botAccountId ? accountId === botAccountId : false;
+  }
+
+  private getInitialTrackingCommentContent(): string {
+    return `## 🤖 Gemini Code Review
+
+⏳ **Status**: Processing your request...
+
+---
+_This comment will be updated with the results._`;
+  }
+}
+
+export const tagMode = new TagMode();

package/src/modes/types.ts

@@ -0,0 +1,95 @@
+/**
+ * Mode System Types
+ * Defines the interface for execution modes (tag, agent)
+ */
+
+import type { ParsedBitbucketContext } from "../bitbucket/types.js";
+import type { BitbucketClient } from "../bitbucket/api/client.js";
+
+export type ModeName = "tag" | "agent";
+
+export interface ModeContext {
+  prompt: string;
+  systemPrompt: string;
+  tools: string[];
+  trackingCommentId?: number;
+  branchName?: string;
+}
+
+export interface ModeOptions {
+  context: ParsedBitbucketContext;
+  client: BitbucketClient;
+  triggerPhrase: string;
+  prompt?: string;
+  branchPrefix?: string;
+  createTrackingComment?: boolean;
+}
+
+export interface ModeResult {
+  success: boolean;
+  modeContext: ModeContext;
+  trackingCommentId?: number;
+  branchName?: string;
+  error?: string;
+}
+
+export interface TriggerCheckResult {
+  shouldTrigger: boolean;
+  reason?: string;
+  userMessage?: string;
+  mentionAuthor?: string;
+}
+
+/**
+ * Mode interface - all modes must implement this
+ */
+export interface Mode {
+  /**
+   * Mode identifier
+   */
+  name: ModeName;
+
+  /**
+   * Human-readable description
+   */
+  description: string;
+
+  /**
+   * Check if this mode should be triggered for the given context
+   */
+  shouldTrigger(
+    context: ParsedBitbucketContext,
+    options: {
+      triggerPhrase: string;
+      prompt?: string;
+    }
+  ): TriggerCheckResult;
+
+  /**
+   * Prepare the mode context (create comments, branches, etc.)
+   */
+  prepare(options: ModeOptions): Promise<ModeResult>;
+
+  /**
+   * Get the system prompt for this mode
+   */
+  getSystemPrompt(context: ParsedBitbucketContext): string;
+
+  /**
+   * Get allowed tools for this mode
+   */
+  getAllowedTools(): string[];
+
+  /**
+   * Check if tracking comment should be created
+   */
+  shouldCreateTrackingComment(): boolean;
+}
+
+/**
+ * Mode registry type
+ */
+export interface ModeRegistry {
+  tag: Mode;
+  agent: Mode;
+}

package/src/utils/env.ts

@@ -0,0 +1,190 @@
+/**
+ * Environment Variable Utilities
+ * Handles environment configuration and validation
+ */
+
+import { z } from "zod";
+
+/**
+ * Required environment variables schema
+ */
+const requiredEnvSchema = z.object({
+  // Bitbucket Pipeline variables
+  BITBUCKET_WORKSPACE: z.string().min(1),
+  BITBUCKET_REPO_SLUG: z.string().min(1),
+  BITBUCKET_COMMIT: z.string().min(1),
+
+  // Gemini API
+  GEMINI_API_KEY: z.string().min(1).optional(),
+  GOOGLE_API_KEY: z.string().min(1).optional(),
+});
+
+/**
+ * Optional environment variables schema
+ */
+const optionalEnvSchema = z.object({
+  // Bitbucket credentials
+  BITBUCKET_ACCESS_TOKEN: z.string().optional(),
+  BITBUCKET_USERNAME: z.string().optional(),
+  BITBUCKET_APP_PASSWORD: z.string().optional(),
+
+  // Pipeline context
+  BITBUCKET_PR_ID: z.string().optional(),
+  BITBUCKET_BRANCH: z.string().optional(),
+  BITBUCKET_BUILD_NUMBER: z.string().optional(),
+  BITBUCKET_PIPELINE_UUID: z.string().optional(),
+  BITBUCKET_STEP_UUID: z.string().optional(),
+
+  // Configuration
+  TRIGGER_PHRASE: z.string().default("@gemini"),
+  GEMINI_MODEL: z.string().default("gemini-2.0-flash"),
+  MODE: z.enum(["tag", "agent"]).optional(),
+  PROMPT: z.string().optional(),
+  CREATE_TRACKING_COMMENT: z.string().default("true"),
+  BOT_ACCOUNT_ID: z.string().optional(),
+
+  // Review presets (comma-separated list)
+  // e.g., "junior,nextjs,security" or "senior,architecture,typescript"
+  REVIEW_PRESETS: z.string().optional(),
+  // Custom additional prompt to append to presets
+  CUSTOM_PROMPT: z.string().optional(),
+
+  // Webhook data
+  TRIGGER_EVENT: z.string().optional(),
+  TRIGGER_TIMESTAMP: z.string().optional(),
+  WEBHOOK_PAYLOAD: z.string().optional(),
+});
+
+export type RequiredEnv = z.infer<typeof requiredEnvSchema>;
+export type OptionalEnv = z.infer<typeof optionalEnvSchema>;
+export type FullEnv = RequiredEnv & OptionalEnv;
+
+/**
+ * Validate required environment variables
+ */
+export function validateRequiredEnv(): RequiredEnv {
+  const result = requiredEnvSchema.safeParse(process.env);
+
+  if (!result.success) {
+    const missing = result.error.errors.map((e) => e.path.join(".")).join(", ");
+    throw new Error(`Missing required environment variables: ${missing}`);
+  }
+
+  // Ensure at least one Gemini API key is set
+  if (!result.data.GEMINI_API_KEY && !result.data.GOOGLE_API_KEY) {
+    throw new Error(
+      "Missing Gemini API key. Set GEMINI_API_KEY or GOOGLE_API_KEY"
+    );
+  }
+
+  return result.data;
+}
+
+/**
+ * Get all environment configuration
+ */
+export function getEnvConfig(): FullEnv {
+  const required = validateRequiredEnv();
+  const optional = optionalEnvSchema.parse(process.env);
+
+  return {
+    ...required,
+    ...optional,
+  };
+}
+
+/**
+ * Get Gemini API key
+ */
+export function getGeminiApiKey(): string {
+  const key = process.env.GEMINI_API_KEY || process.env.GOOGLE_API_KEY;
+  if (!key) {
+    throw new Error(
+      "Missing Gemini API key. Set GEMINI_API_KEY or GOOGLE_API_KEY"
+    );
+  }
+  return key;
+}
+
+/**
+ * Get Bitbucket credentials
+ */
+export function getBitbucketCredentials(): {
+  type: "token" | "basic";
+  accessToken?: string;
+  username?: string;
+  appPassword?: string;
+} {
+  const accessToken = process.env.BITBUCKET_ACCESS_TOKEN;
+  const username = process.env.BITBUCKET_USERNAME;
+  const appPassword = process.env.BITBUCKET_APP_PASSWORD;
+
+  if (accessToken) {
+    return { type: "token", accessToken };
+  }
+
+  if (username && appPassword) {
+    return { type: "basic", username, appPassword };
+  }
+
+  throw new Error(
+    "Missing Bitbucket credentials. Set BITBUCKET_ACCESS_TOKEN or BITBUCKET_USERNAME and BITBUCKET_APP_PASSWORD"
+  );
+}
+
+/**
+ * Get pipeline URL
+ */
+export function getPipelineUrl(): string | undefined {
+  const workspace = process.env.BITBUCKET_WORKSPACE;
+  const repoSlug = process.env.BITBUCKET_REPO_SLUG;
+  const pipelineUuid = process.env.BITBUCKET_PIPELINE_UUID;
+
+  if (workspace && repoSlug && pipelineUuid) {
+    return `https://bitbucket.org/${workspace}/${repoSlug}/pipelines/results/${pipelineUuid}`;
+  }
+
+  return undefined;
+}
+
+/**
+ * Check if running in CI environment
+ */
+export function isCI(): boolean {
+  return (
+    !!process.env.BITBUCKET_PIPELINE_UUID || process.env.CI === "true"
+  );
+}
+
+/**
+ * Get boolean from env variable
+ */
+export function getEnvBool(key: string, defaultValue: boolean = false): boolean {
+  const value = process.env[key];
+  if (value === undefined) {
+    return defaultValue;
+  }
+  return value.toLowerCase() === "true" || value === "1";
+}
+
+/**
+ * Parse review presets from environment variable
+ * @returns Array of preset keys
+ */
+export function getReviewPresets(): string[] {
+  const presets = process.env.REVIEW_PRESETS;
+  if (!presets) {
+    return [];
+  }
+  return presets
+    .split(",")
+    .map((p) => p.trim().toLowerCase())
+    .filter((p) => p.length > 0);
+}
+
+/**
+ * Get custom prompt from environment variable
+ */
+export function getCustomPrompt(): string | undefined {
+  return process.env.CUSTOM_PROMPT;
+}