ra2-eva-cursor-hooks 1.0.0

package/src/player.ts

@@ -0,0 +1,230 @@
+/// <reference types="bun-types" />
+/**
+ * Red Alert 2 EVA Audio Player
+ * Plays WAV files using macOS afplay command
+ * Includes audio queue to prevent overlapping sounds
+ */
+
+import { spawnSync } from "bun";
+import { existsSync, unlinkSync, writeFileSync } from "fs";
+import { dirname, resolve } from "path";
+import { SOUND_MAPPINGS, getStopSoundKey } from "./sounds";
+import type { Faction, HookInput, PostToolUseInput, StopInput } from "./types";
+
+// Resolve assets directory relative to this file
+const SCRIPT_DIR = dirname(Bun.main);
+const ASSETS_DIR = resolve(SCRIPT_DIR, "assets");
+
+// Lock file for audio queue
+const LOCK_FILE = "/tmp/ra2-eva-audio.lock";
+const MAX_WAIT_MS = 10000; // Max 10 seconds to wait for lock
+const POLL_INTERVAL_MS = 50; // Check every 50ms
+
+/**
+ * Acquire the audio lock (blocks until available or timeout)
+ */
+async function acquireLock(): Promise<boolean> {
+  const startTime = Date.now();
+
+  while (existsSync(LOCK_FILE)) {
+    // Check if lock is stale (older than 5 seconds = stuck process)
+    try {
+      const stat = Bun.file(LOCK_FILE);
+      const lockTime = parseInt(await stat.text(), 10);
+      if (Date.now() - lockTime > 5000) {
+        // Stale lock, remove it
+        try {
+          unlinkSync(LOCK_FILE);
+        } catch {}
+        break;
+      }
+    } catch {}
+
+    // Timeout check
+    if (Date.now() - startTime > MAX_WAIT_MS) {
+      console.error("[EVA] Timeout waiting for audio lock");
+      return false;
+    }
+
+    await Bun.sleep(POLL_INTERVAL_MS);
+  }
+
+  // Create lock with current timestamp
+  try {
+    writeFileSync(LOCK_FILE, Date.now().toString());
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Release the audio lock
+ */
+function releaseLock(): void {
+  try {
+    unlinkSync(LOCK_FILE);
+  } catch {}
+}
+
+/**
+ * Get the current faction based on hour
+ * Odd hours = Allied, Even hours = Soviet
+ */
+export function getFaction(): Faction {
+  const hour = new Date().getHours();
+  return hour % 2 === 1 ? "allied" : "soviet";
+}
+
+/**
+ * Get a random element from an array
+ */
+function randomChoice<T>(arr: T[]): T {
+  return arr[Math.floor(Math.random() * arr.length)];
+}
+
+/**
+ * Get the sound file path for a hook event
+ */
+export function getSoundPath(
+  hookType: string,
+  faction: Faction
+): string | null {
+  const mapping = SOUND_MAPPINGS[hookType];
+  if (!mapping) {
+    console.error(`[EVA] No sound mapping for hook: ${hookType}`);
+    return null;
+  }
+
+  const sounds = mapping[faction];
+  if (!sounds || sounds.length === 0) {
+    return null;
+  }
+
+  const soundFile = randomChoice(sounds);
+  const factionDir = faction === "allied" ? "eva_allied" : "eva_soviet";
+
+  return resolve(ASSETS_DIR, factionDir, soundFile);
+}
+
+/**
+ * Determine the sound key for lookup
+ * Handles special cases like stop with different statuses
+ * Returns null to skip playing sound for this hook
+ */
+export function getSoundKey(input: HookInput): string | null {
+  const hookName = input.hook_event_name;
+
+  // Handle stop hook with status-based sounds
+  if (hookName === "stop") {
+    const stopInput = input as StopInput;
+    return getStopSoundKey(stopInput.status);
+  }
+
+  // Handle preToolUse - skip for tools with dedicated hooks
+  if (hookName === "preToolUse") {
+    const toolInput = input as PostToolUseInput;
+    if (toolInput.tool_name === "Shell") {
+      return null; // Skip - beforeShellExecution handles shell
+    }
+    if (toolInput.tool_name === "Read") {
+      return null; // Skip - beforeReadFile handles read
+    }
+    if (
+      toolInput.tool_name === "Write" ||
+      toolInput.tool_name === "StrReplace"
+    ) {
+      return null; // Skip - afterFileEdit handles write/edit
+    }
+  }
+
+  // Handle postToolUse - skip for tools with dedicated hooks
+  if (hookName === "postToolUse") {
+    const toolInput = input as PostToolUseInput;
+    // Skip Shell - afterShellExecution handles it
+    if (toolInput.tool_name === "Shell") {
+      return null;
+    }
+    // Skip Read - no sound needed after reading
+    if (toolInput.tool_name === "Read") {
+      return null;
+    }
+    // Skip Write/StrReplace - afterFileEdit handles it
+    if (
+      toolInput.tool_name === "Write" ||
+      toolInput.tool_name === "StrReplace"
+    ) {
+      return null;
+    }
+    // Delete tool plays "Unit lost" - something was destroyed!
+    if (toolInput.tool_name === "Delete") {
+      return "postToolUseFailure"; // Maps to "Unit lost"
+    }
+  }
+
+  // Handle postToolUseFailure - skip Read failures (often just "file doesn't exist" checks)
+  if (hookName === "postToolUseFailure") {
+    const toolInput = input as PostToolUseInput;
+    if (toolInput.tool_name === "Read") {
+      return null; // Skip - file not existing is expected when checking before create
+    }
+  }
+
+  return hookName;
+}
+
+/**
+ * Play a WAV file with queue support
+ * Waits for previous audio to finish before playing
+ */
+export async function playSound(filePath: string): Promise<void> {
+  try {
+    // Check if file exists
+    const file = Bun.file(filePath);
+    if (!(await file.exists())) {
+      console.error(`[EVA] Sound file not found: ${filePath}`);
+      return;
+    }
+
+    // Acquire lock (wait for previous audio to finish)
+    const gotLock = await acquireLock();
+    if (!gotLock) {
+      console.error(
+        `[EVA] Could not acquire audio lock, skipping: ${filePath}`
+      );
+      return;
+    }
+
+    console.error(`[EVA] Playing: ${filePath}`);
+
+    try {
+      // Play audio SYNCHRONOUSLY (wait for it to finish)
+      spawnSync({
+        cmd: ["afplay", filePath],
+        stdout: "ignore",
+        stderr: "ignore",
+      });
+    } finally {
+      // Always release lock
+      releaseLock();
+    }
+  } catch (error) {
+    console.error(`[EVA] Error playing sound: ${error}`);
+    releaseLock(); // Ensure lock is released on error
+  }
+}
+
+/**
+ * Play the appropriate EVA sound for a hook event
+ */
+export async function playHookSound(input: HookInput): Promise<void> {
+  const faction = getFaction();
+  const soundKey = getSoundKey(input);
+  const soundPath = getSoundPath(soundKey, faction);
+
+  console.error(`[EVA] Faction: ${faction}, Sound key: ${soundKey}`);
+
+  if (soundPath) {
+    await playSound(soundPath);
+  }
+}

package/src/sounds.ts

@@ -0,0 +1,176 @@
+/**
+ * Red Alert 2 EVA Sound Mappings
+ * Maps hook events to EVA voice lines for both Allied and Soviet factions
+ */
+
+import type { SoundMapping } from "./types";
+
+/**
+ * Sound mappings for each hook event
+ * Allied files: ceva###.wav
+ * Soviet files: csof###.wav (same numbers, different prefix)
+ *
+ * Hook event names use camelCase as per Cursor docs
+ */
+export const SOUND_MAPPINGS: Record<string, SoundMapping> = {
+  // ============================================================
+  // Session Lifecycle
+  // ============================================================
+
+  sessionStart: {
+    // "Establishing battlefield control. Stand by."
+    allied: ["ceva016.wav"],
+    soviet: ["csof016.wav"],
+  },
+
+  sessionEnd: {
+    // "Battle control terminated."
+    allied: ["ceva015.wav"],
+    soviet: ["csof015.wav"],
+  },
+
+  // ============================================================
+  // Tool Operations
+  // ============================================================
+
+  preToolUse: {
+    // "Building."
+    allied: ["ceva052.wav"],
+    soviet: ["csof052.wav"],
+  },
+
+  postToolUse: {
+    // "Unit ready."
+    allied: ["ceva062.wav"],
+    soviet: ["csof062.wav"],
+  },
+
+  postToolUseFailure: {
+    // "Unit lost."
+    allied: ["ceva064.wav"],
+    soviet: ["csof064.wav"],
+  },
+
+  // ============================================================
+  // Shell Commands
+  // ============================================================
+
+  beforeShellExecution: {
+    // "Building."
+    allied: ["ceva052.wav"],
+    soviet: ["csof052.wav"],
+  },
+
+  afterShellExecution: {
+    // "Unit ready."
+    allied: ["ceva062.wav"],
+    soviet: ["csof062.wav"],
+  },
+
+  // ============================================================
+  // File Operations
+  // ============================================================
+
+  beforeReadFile: {
+    // "Training." (training the LLM!)
+    allied: ["ceva066.wav"],
+    soviet: ["csof066.wav"],
+  },
+
+  afterFileEdit: {
+    // "Unit promoted." (file improved!)
+    allied: ["ceva079.wav"],
+    soviet: ["csof079.wav"],
+  },
+
+  // ============================================================
+  // MCP Tools (Special Technology!)
+  // ============================================================
+
+  beforeMCPExecution: {
+    // "Upgrade in progress."
+    allied: ["ceva084.wav"],
+    soviet: ["csof084.wav"],
+  },
+
+  afterMCPExecution: {
+    // "New technology acquired."
+    allied: ["ceva074.wav"],
+    soviet: ["csof074.wav"],
+  },
+
+  // ============================================================
+  // Prompts
+  // ============================================================
+
+  beforeSubmitPrompt: {
+    // "New mission objective received." / "New construction options."
+    allied: ["ceva083.wav", "ceva049.wav"],
+    soviet: ["csof083.wav", "csof049.wav"],
+  },
+
+  // ============================================================
+  // Subagents (Reinforcements!)
+  // ============================================================
+
+  subagentStart: {
+    // Random: "Reinforcements have arrived." / "Reinforcements ready."
+    allied: ["ceva038.wav", "ceva121.wav"],
+    soviet: ["csof038.wav", "csof121.wav"],
+  },
+
+  subagentStop: {
+    // Random: "Primary/Secondary/Tertiary objective achieved."
+    allied: ["ceva017.wav", "ceva018.wav", "ceva019.wav"],
+    soviet: ["csof017.wav", "csof018.wav", "csof019.wav"],
+  },
+
+  // ============================================================
+  // Agent Stop (Status-based)
+  // ============================================================
+
+  "stop:completed": {
+    // "Construction complete." / "Primary objective achieved."
+    allied: ["ceva048.wav", "ceva017.wav"],
+    soviet: ["csof048.wav", "csof017.wav"],
+  },
+
+  "stop:aborted": {
+    // "Cancelled."
+    allied: ["ceva051.wav"],
+    soviet: ["csof051.wav"],
+  },
+
+  "stop:error": {
+    // "Cannot deploy here."
+    allied: ["ceva063.wav"],
+    soviet: ["csof063.wav"],
+  },
+
+  // ============================================================
+  // Agent Thoughts
+  // ============================================================
+
+  afterAgentThought: {
+    // "Incoming transmission." (agent finished thinking)
+    allied: ["ceva040.wav"],
+    soviet: ["csof040.wav"],
+  },
+
+  // ============================================================
+  // Context Management
+  // ============================================================
+
+  preCompact: {
+    // Random: "Low power." / "Base defenses offline." / "Building offline."
+    allied: ["ceva053.wav"],
+    soviet: ["csof053.wav"],
+  },
+};
+
+/**
+ * Get the sound key for a stop event based on status
+ */
+export function getStopSoundKey(status: string): string {
+  return `stop:${status}`;
+}

package/src/types.ts

@@ -0,0 +1,241 @@
+/**
+ * Red Alert 2 EVA Cursor Hooks - TypeScript Types
+ * Based on Cursor's hook specification
+ */
+
+// ============================================================
+// Common Input Fields (all hooks receive these)
+// ============================================================
+
+export interface CommonHookInput {
+  conversation_id: string;
+  generation_id: string;
+  model: string;
+  hook_event_name: string;
+  cursor_version: string;
+  workspace_roots: string[];
+  user_email: string | null;
+  transcript_path: string | null;
+}
+
+// ============================================================
+// Hook-Specific Input Types
+// ============================================================
+
+export interface SessionStartInput extends CommonHookInput {
+  hook_event_name: "sessionStart";
+  session_id: string;
+  is_background_agent: boolean;
+  composer_mode?: "agent" | "ask" | "edit";
+}
+
+export interface SessionEndInput extends CommonHookInput {
+  hook_event_name: "sessionEnd";
+  session_id: string;
+  reason: "completed" | "aborted" | "error" | "window_close" | "user_close";
+  duration_ms: number;
+  is_background_agent: boolean;
+  final_status: string;
+  error_message?: string;
+}
+
+export interface PreToolUseInput extends CommonHookInput {
+  hook_event_name: "preToolUse";
+  tool_name: string;
+  tool_input: Record<string, unknown>;
+  tool_use_id: string;
+  cwd: string;
+  agent_message?: string;
+}
+
+export interface PostToolUseInput extends CommonHookInput {
+  hook_event_name: "postToolUse";
+  tool_name: string;
+  tool_input: Record<string, unknown>;
+  tool_output: string;
+  tool_use_id: string;
+  cwd: string;
+  duration: number;
+}
+
+export interface PostToolUseFailureInput extends CommonHookInput {
+  hook_event_name: "postToolUseFailure";
+  tool_name: string;
+  tool_input: Record<string, unknown>;
+  tool_use_id: string;
+  cwd: string;
+  error_message: string;
+  failure_type: "timeout" | "error" | "permission_denied";
+  duration: number;
+  is_interrupt: boolean;
+}
+
+export interface BeforeShellExecutionInput extends CommonHookInput {
+  hook_event_name: "beforeShellExecution";
+  command: string;
+  cwd: string;
+  timeout: number;
+}
+
+export interface AfterShellExecutionInput extends CommonHookInput {
+  hook_event_name: "afterShellExecution";
+  command: string;
+  output: string;
+  duration: number;
+}
+
+export interface BeforeReadFileInput extends CommonHookInput {
+  hook_event_name: "beforeReadFile";
+  file_path: string;
+  content: string;
+  attachments?: Array<{ type: "file" | "rule"; filePath: string }>;
+}
+
+export interface AfterFileEditInput extends CommonHookInput {
+  hook_event_name: "afterFileEdit";
+  file_path: string;
+  edits: Array<{ old_string: string; new_string: string }>;
+}
+
+export interface BeforeMCPExecutionInput extends CommonHookInput {
+  hook_event_name: "beforeMCPExecution";
+  tool_name: string;
+  tool_input: string;
+  url?: string;
+  command?: string;
+}
+
+export interface AfterMCPExecutionInput extends CommonHookInput {
+  hook_event_name: "afterMCPExecution";
+  tool_name: string;
+  tool_input: string;
+  result_json: string;
+  duration: number;
+}
+
+export interface BeforeSubmitPromptInput extends CommonHookInput {
+  hook_event_name: "beforeSubmitPrompt";
+  prompt: string;
+  attachments?: Array<{ type: "file" | "rule"; filePath: string }>;
+}
+
+export interface SubagentStartInput extends CommonHookInput {
+  hook_event_name: "subagentStart";
+  subagent_type: string;
+  prompt: string;
+}
+
+export interface SubagentStopInput extends CommonHookInput {
+  hook_event_name: "subagentStop";
+  subagent_type: string;
+  status: "completed" | "error";
+  result: string;
+  duration: number;
+  agent_transcript_path?: string | null;
+}
+
+export interface StopInput extends CommonHookInput {
+  hook_event_name: "stop";
+  status: "completed" | "aborted" | "error";
+  loop_count: number;
+}
+
+export interface PreCompactInput extends CommonHookInput {
+  hook_event_name: "preCompact";
+  trigger: "auto" | "manual";
+  context_usage_percent: number;
+  context_tokens: number;
+  context_window_size: number;
+  message_count: number;
+  messages_to_compact: number;
+  is_first_compaction: boolean;
+}
+
+// Union of all hook inputs
+export type HookInput =
+  | SessionStartInput
+  | SessionEndInput
+  | PreToolUseInput
+  | PostToolUseInput
+  | PostToolUseFailureInput
+  | BeforeShellExecutionInput
+  | AfterShellExecutionInput
+  | BeforeReadFileInput
+  | AfterFileEditInput
+  | BeforeMCPExecutionInput
+  | AfterMCPExecutionInput
+  | BeforeSubmitPromptInput
+  | SubagentStartInput
+  | SubagentStopInput
+  | StopInput
+  | PreCompactInput;
+
+// ============================================================
+// Hook Output Types
+// ============================================================
+
+export interface SessionStartOutput {
+  env?: Record<string, string>;
+  additional_context?: string;
+  continue?: boolean;
+  user_message?: string;
+}
+
+export interface PreToolUseOutput {
+  decision?: "allow" | "deny";
+  reason?: string;
+  updated_input?: Record<string, unknown>;
+}
+
+export interface PostToolUseOutput {
+  updated_mcp_tool_output?: Record<string, unknown>;
+}
+
+export interface BeforeShellExecutionOutput {
+  permission?: "allow" | "deny" | "ask";
+  user_message?: string;
+  agent_message?: string;
+}
+
+export interface BeforeReadFileOutput {
+  permission?: "allow" | "deny";
+  user_message?: string;
+}
+
+export interface BeforeSubmitPromptOutput {
+  continue?: boolean;
+  user_message?: string;
+}
+
+export interface SubagentStartOutput {
+  decision?: "allow" | "deny";
+  reason?: string;
+}
+
+export interface SubagentStopOutput {
+  followup_message?: string;
+}
+
+export interface StopOutput {
+  followup_message?: string;
+}
+
+export interface PreCompactOutput {
+  user_message?: string;
+}
+
+// Empty output for observation-only hooks
+export interface EmptyOutput {}
+
+// ============================================================
+// Sound Types
+// ============================================================
+
+export type Faction = "allied" | "soviet";
+
+export type HookEventName = HookInput["hook_event_name"];
+
+export interface SoundMapping {
+  allied: string[];
+  soviet: string[];
+}