dota2-hero-sounds 1.0.0

package/README.md

@@ -0,0 +1,107 @@
+# dota2-hero-sounds
+
+Dota 2 hero voice line notifications for [Claude Code](https://docs.anthropic.com/en/docs/claude-code), [OpenCode](https://opencode.ai), and [Pi](https://pi.dev). Get notified with voice lines from Axe, Crystal Maiden, Pudge, Zeus, and many more when your AI coding assistant completes tasks, hits errors, or needs your attention.
+
+## Quick Start
+
+```bash
+npx dota2-hero-sounds install
+```
+
+This auto-detects which tools you have installed and configures them. Use flags to target a specific tool:
+
+```bash
+npx dota2-hero-sounds install --claude     # Claude Code only
+npx dota2-hero-sounds install --opencode   # OpenCode only
+npx dota2-hero-sounds install --pi         # Pi only
+npx dota2-hero-sounds install --all        # All three
+```
+
+## How It Works
+
+When events occur in your coding tool, a random hero speaks:
+
+| Event | Category | Example Lines |
+|-------|----------|---------------|
+| Task complete | `success` | "Yes, Axe kills you!", "Burns, doesn't it?", "Told you a storm was coming!" |
+| Error | `error` | "An anchor around my neck!", "Okay, sure, I've made some mistakes.", "That was just a warm-up." |
+| Needs attention | `attention` | "Come to Pudge!", "Prepare thyself.", "Agony awaits." |
+| Session start | `start` | "Let the carnage begin!", "Storm Spirit is alive!", "Your God has arrived." |
+
+A random sound is picked from the matching category each time. Sounds have a 3-second cooldown to prevent overlapping voice lines.
+
+## Hero Selection
+
+By default, sounds are picked randomly from all heroes. You can set preferred heroes:
+
+```bash
+npx dota2-hero-sounds hero list          # Show available heroes with sound counts
+npx dota2-hero-sounds hero set axe pudge # Only play Axe and Pudge sounds
+npx dota2-hero-sounds hero show          # Show current preference
+npx dota2-hero-sounds hero clear         # Reset to all heroes
+```
+
+Hero preferences are saved to `~/.config/dota2-sounds/config.json` and take effect immediately — no reinstall needed. If a selected hero has no sounds for a category, it falls back to all heroes for that category.
+
+## CLI Commands
+
+```bash
+dota2-hero-sounds install     # Install hooks/plugins
+dota2-hero-sounds uninstall   # Remove everything cleanly
+dota2-hero-sounds test        # Play one sound per category
+dota2-hero-sounds list        # Show all sounds by category
+dota2-hero-sounds hero list   # Show heroes with per-category counts
+dota2-hero-sounds hero set    # Set preferred heroes
+dota2-hero-sounds help        # Show help
+```
+
+## What Gets Installed
+
+**Claude Code** — Hooks added to `~/.claude/settings.json`:
+- `Stop` → plays success sound
+- `PostToolUseFailure` → plays error sound
+- `Notification` → plays attention sound
+- `SessionStart` → plays start sound
+
+**OpenCode** — Plugin written to `~/.config/opencode/plugins/dota2-sounds.js`:
+- `session.status` busy→idle transition → plays success sound
+- `session.error` → plays error sound
+- `permission.asked` → plays attention sound
+- Plugin init → plays start sound (session.created fires too early)
+
+**Pi** — Extension installed via `pi install` as a Pi package:
+- `session_start` → plays start sound
+- `agent_end` → plays success sound
+- `tool_execution_end` (when `isError`) → plays error sound
+- `session_shutdown` → plays error sound
+- *Attention sound not available* — Pi has no permission/notification event
+
+## Uninstall
+
+```bash
+npx dota2-hero-sounds uninstall
+```
+
+This cleanly removes only the hooks/plugins added by this package — your other settings are untouched.
+
+## Adding Custom Sounds
+
+1. Add `.mp3` files to the appropriate `sounds/<category>/` subdirectory
+2. Sound files are discovered at runtime — no code changes needed
+3. Re-run `dota2-hero-sounds install` to update the OpenCode plugin with new sounds
+
+Sound files should follow the naming convention `Vo_<hero>_<shortname>_<type>_<num>.mp3` to enable future hero-based filtering.
+
+## Finding More Sounds
+
+Browse the full collection of Dota 2 hero voice lines at the [Dota 2 Wiki Audio Category](https://dota2.fandom.com/wiki/Category:Audio). Each hero has hundreds of voice lines covering spawns, kills, abilities, and more.
+
+## Requirements
+
+- **macOS** (uses `afplay` for audio playback)
+- **Node.js** 18+
+- Claude Code, OpenCode, and/or Pi installed
+
+## License
+
+MIT

package/dist/claude-hooks.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Get the path to Claude Code's global settings file.
+ */
+export declare function getClaudeSettingsPath(): string;
+/**
+ * Check if Claude Code config directory exists.
+ */
+export declare function isClaudeCodeAvailable(): boolean;
+/**
+ * Install Claude Code hooks into ~/.claude/settings.json.
+ * Merges with existing hooks without overwriting user-defined ones.
+ */
+export declare function installClaudeHooks(playScriptPath: string): void;
+/**
+ * Remove all dota2-hero-sounds hooks from ~/.claude/settings.json.
+ */
+export declare function uninstallClaudeHooks(): void;

package/dist/claude-hooks.js

@@ -0,0 +1,106 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+/**
+ * Marker used to identify hooks added by this package,
+ * so we can cleanly uninstall without touching user-defined hooks.
+ */
+const HOOK_MARKER = 'dota2-hero-sounds';
+/**
+ * Get the path to Claude Code's global settings file.
+ */
+export function getClaudeSettingsPath() {
+    return join(homedir(), '.claude', 'settings.json');
+}
+/**
+ * Check if Claude Code config directory exists.
+ */
+export function isClaudeCodeAvailable() {
+    return existsSync(join(homedir(), '.claude'));
+}
+/**
+ * Build the hooks configuration for Claude Code.
+ * @param playScriptPath - Absolute path to dist/play.js
+ */
+function buildHooks(playScriptPath) {
+    const makeHook = (category) => ({
+        matcher: '',
+        hooks: [
+            {
+                type: 'command',
+                command: `node "${playScriptPath}" ${category} # ${HOOK_MARKER}`,
+            },
+        ],
+    });
+    return {
+        Stop: [makeHook('success')],
+        PostToolUseFailure: [makeHook('error')],
+        Notification: [makeHook('attention')],
+        SessionStart: [makeHook('start')],
+    };
+}
+/**
+ * Install Claude Code hooks into ~/.claude/settings.json.
+ * Merges with existing hooks without overwriting user-defined ones.
+ */
+export function installClaudeHooks(playScriptPath) {
+    const settingsPath = getClaudeSettingsPath();
+    const settingsDir = join(homedir(), '.claude');
+    // Ensure directory exists
+    if (!existsSync(settingsDir)) {
+        mkdirSync(settingsDir, { recursive: true });
+    }
+    // Read existing settings or start fresh
+    let settings = {};
+    if (existsSync(settingsPath)) {
+        const raw = readFileSync(settingsPath, 'utf-8');
+        settings = JSON.parse(raw);
+    }
+    // Remove any existing dota2-hero-sounds hooks first (clean reinstall)
+    if (settings.hooks) {
+        for (const event of Object.keys(settings.hooks)) {
+            settings.hooks[event] = settings.hooks[event].filter((entry) => !entry.hooks.some((h) => h.command.includes(HOOK_MARKER)));
+            // Remove the event key entirely if no hooks remain
+            if (settings.hooks[event].length === 0) {
+                delete settings.hooks[event];
+            }
+        }
+    }
+    // Merge new hooks
+    const newHooks = buildHooks(playScriptPath);
+    if (!settings.hooks) {
+        settings.hooks = {};
+    }
+    for (const [event, hookEntries] of Object.entries(newHooks)) {
+        if (!settings.hooks[event]) {
+            settings.hooks[event] = [];
+        }
+        settings.hooks[event].push(...hookEntries);
+    }
+    writeFileSync(settingsPath, `${JSON.stringify(settings, null, 2)}\n`, 'utf-8');
+}
+/**
+ * Remove all dota2-hero-sounds hooks from ~/.claude/settings.json.
+ */
+export function uninstallClaudeHooks() {
+    const settingsPath = getClaudeSettingsPath();
+    if (!existsSync(settingsPath)) {
+        return;
+    }
+    const raw = readFileSync(settingsPath, 'utf-8');
+    const settings = JSON.parse(raw);
+    if (!settings.hooks) {
+        return;
+    }
+    for (const event of Object.keys(settings.hooks)) {
+        settings.hooks[event] = settings.hooks[event].filter((entry) => !entry.hooks.some((h) => h.command.includes(HOOK_MARKER)));
+        if (settings.hooks[event].length === 0) {
+            delete settings.hooks[event];
+        }
+    }
+    // Remove hooks key entirely if empty
+    if (Object.keys(settings.hooks).length === 0) {
+        delete settings.hooks;
+    }
+    writeFileSync(settingsPath, `${JSON.stringify(settings, null, 2)}\n`, 'utf-8');
+}

package/dist/cli.d.ts

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+declare const program: Command;
+export { program };

package/dist/cli.js

@@ -0,0 +1,229 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import { getClaudeSettingsPath, installClaudeHooks, isClaudeCodeAvailable, uninstallClaudeHooks, } from './claude-hooks.js';
+import { readConfig, writeConfig } from './config.js';
+import { filterSoundsByHeroes, getAvailableHeroes } from './heroes.js';
+import { copyRuntimeFiles, getInstalledPiExtensionDir, getInstalledPlayScript, getInstalledSoundsDir, removeRuntimeFiles, } from './install-files.js';
+import { getOpenCodePluginPath, installOpenCodePlugin, isOpenCodeAvailable, uninstallOpenCodePlugin, } from './opencode-plugin.js';
+import { getPiExtensionPath, installPiExtension, isPiAvailable, uninstallPiExtension, } from './pi-extension.js';
+import { CATEGORIES, listSounds, playSound } from './play-sound.js';
+// ── Helpers ──────────────────────────────────────────────────────────
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+// ── Program ──────────────────────────────────────────────────────────
+const program = new Command();
+program
+    .name('dota2-hero-sounds')
+    .description('Dota 2 hero voice notifications for Claude Code, OpenCode, and Pi')
+    .version('1.0.0');
+// ── install ──────────────────────────────────────────────────────────
+program
+    .command('install')
+    .description('Install hooks/plugins for detected tools')
+    .option('--claude', 'Install Claude Code hooks only')
+    .option('--opencode', 'Install OpenCode plugin only')
+    .option('--pi', 'Install Pi coding agent extension only')
+    .option('--all', 'Install for all supported tools')
+    .action(async (opts) => {
+    const wantClaude = opts.claude || opts.all;
+    const wantOpenCode = opts.opencode || opts.all;
+    const wantPi = opts.pi || opts.all;
+    const autoDetect = !wantClaude && !wantOpenCode && !wantPi;
+    let installedAny = false;
+    // Copy runtime files to permanent location first
+    copyRuntimeFiles();
+    const playScriptPath = getInstalledPlayScript();
+    const soundsDir = getInstalledSoundsDir();
+    // Claude Code
+    const claudeAvailable = isClaudeCodeAvailable();
+    const shouldInstallClaude = wantClaude || (autoDetect && claudeAvailable);
+    if (shouldInstallClaude) {
+        if (!claudeAvailable) {
+            console.error('Error: Claude Code config directory (~/.claude/) not found. Is Claude Code installed?');
+        }
+        else {
+            installClaudeHooks(playScriptPath);
+            console.log('[+] Claude Code hooks installed');
+            console.log(`    Config: ${getClaudeSettingsPath()}`);
+            installedAny = true;
+        }
+    }
+    // OpenCode
+    const openCodeAvailable = isOpenCodeAvailable();
+    const shouldInstallOpenCode = wantOpenCode || (autoDetect && openCodeAvailable);
+    if (shouldInstallOpenCode) {
+        if (!openCodeAvailable) {
+            console.error('Error: OpenCode config directory (~/.config/opencode/) not found. Is OpenCode installed?');
+        }
+        else {
+            installOpenCodePlugin(soundsDir);
+            console.log('[+] OpenCode plugin installed');
+            console.log(`    Plugin: ${getOpenCodePluginPath()}`);
+            installedAny = true;
+        }
+    }
+    // Pi
+    const piAvailable = isPiAvailable();
+    const shouldInstallPi = wantPi || (autoDetect && piAvailable);
+    if (shouldInstallPi) {
+        if (!piAvailable) {
+            console.error('Error: Pi config directory (~/.pi/agent/) not found. Is Pi installed?');
+        }
+        else {
+            installPiExtension(getInstalledPiExtensionDir());
+            console.log('[+] Pi extension installed');
+            console.log(`    Extension: ${getPiExtensionPath()}`);
+            installedAny = true;
+        }
+    }
+    if (!installedAny) {
+        console.log('No supported tools detected. Use --claude, --opencode, or --pi to force install.');
+        console.log('');
+        console.log('Supported tools:');
+        console.log('  Claude Code  (~/.claude/)');
+        console.log('  OpenCode     (~/.config/opencode/)');
+        console.log('  Pi           (~/.pi/agent/)');
+        process.exitCode = 1;
+        return;
+    }
+    console.log('');
+    console.log('Dota 2 Axe is ready. Good luck, have fun!');
+});
+// ── uninstall ────────────────────────────────────────────────────────
+program
+    .command('uninstall')
+    .description('Remove all hooks and plugins')
+    .option('--claude', 'Remove Claude Code hooks only')
+    .option('--opencode', 'Remove OpenCode plugin only')
+    .option('--pi', 'Remove Pi extension only')
+    .action((opts) => {
+    const removeAll = !opts.claude && !opts.opencode && !opts.pi;
+    if (removeAll || opts.claude) {
+        uninstallClaudeHooks();
+        console.log('[-] Claude Code hooks removed');
+    }
+    if (removeAll || opts.opencode) {
+        uninstallOpenCodePlugin();
+        console.log('[-] OpenCode plugin removed');
+    }
+    if (removeAll || opts.pi) {
+        uninstallPiExtension();
+        console.log('[-] Pi extension removed');
+    }
+    if (removeAll) {
+        removeRuntimeFiles();
+        console.log('[-] Runtime files removed');
+    }
+    console.log('');
+    console.log('Axe is not Axe! (sounds removed)');
+});
+// ── test ─────────────────────────────────────────────────────────────
+program
+    .command('test')
+    .description('Play one sound from each category')
+    .argument('[category]', 'Play a specific category only')
+    .action(async (category) => {
+    if (category) {
+        if (!listSounds()[category]) {
+            console.error(`Unknown category: ${category}`);
+            console.error(`Available: ${[...CATEGORIES].join(', ')}`);
+            process.exitCode = 1;
+            return;
+        }
+        console.log(`Playing: ${category}`);
+        playSound(category);
+        return;
+    }
+    console.log('Testing all sound categories...\n');
+    for (const cat of [...CATEGORIES]) {
+        console.log(`  Playing: ${cat}`);
+        playSound(cat);
+        await sleep(2000);
+    }
+    console.log('\nDone. If you heard Axe, everything is working.');
+});
+// ── list ─────────────────────────────────────────────────────────────
+program
+    .command('list')
+    .description('Show all available sounds by category')
+    .action(() => {
+    const config = readConfig();
+    const allSounds = listSounds();
+    if (config.heroes.length > 0) {
+        console.log(`Dota 2 Sound Categories (filtered: ${config.heroes.join(', ')})\n`);
+    }
+    else {
+        console.log('Dota 2 Sound Categories\n');
+    }
+    for (const [cat, sounds] of Object.entries(allSounds)) {
+        const filtered = config.heroes.length > 0 ? filterSoundsByHeroes(sounds, config.heroes) : sounds;
+        console.log(`  ${cat}: (${filtered.length} sounds)`);
+        for (const sound of filtered) {
+            const name = sound.replace(/^.*\//, '').replace('.mp3', '');
+            console.log(`    - ${name}`);
+        }
+        console.log('');
+    }
+});
+// ── hero ─────────────────────────────────────────────────────────────
+const hero = program.command('hero').description('Manage hero preferences');
+hero
+    .command('set')
+    .description('Set preferred heroes')
+    .argument('<heroes...>', 'Hero keys (e.g., axe pudge lina)')
+    .action((heroes) => {
+    const available = getAvailableHeroes();
+    const validKeys = new Set(available.map((h) => h.key));
+    const invalid = heroes.filter((h) => !validKeys.has(h));
+    if (invalid.length > 0) {
+        console.error(`Unknown hero(es): ${invalid.join(', ')}`);
+        console.error(`Run 'dota2-hero-sounds hero list' to see available heroes`);
+        process.exitCode = 1;
+        return;
+    }
+    writeConfig({ heroes });
+    console.log(`Heroes set: ${heroes.join(', ')}`);
+});
+hero
+    .command('list')
+    .description('Show available heroes with sound counts')
+    .action(() => {
+    const heroes = getAvailableHeroes();
+    const config = readConfig();
+    const selected = new Set(config.heroes);
+    console.log('Available Heroes\n');
+    console.log(`  ${'Hero'.padEnd(20)} ${'Success'.padEnd(9)} ${'Error'.padEnd(9)} ${'Attention'.padEnd(11)} ${'Start'.padEnd(9)} Total`);
+    console.log(`  ${'─'.repeat(20)} ${'─'.repeat(9)} ${'─'.repeat(9)} ${'─'.repeat(11)} ${'─'.repeat(9)} ${'─'.repeat(5)}`);
+    for (const h of heroes) {
+        const marker = selected.has(h.key) ? ' *' : '';
+        console.log(`  ${(h.key + marker).padEnd(20)} ${String(h.counts.success).padEnd(9)} ${String(h.counts.error).padEnd(9)} ${String(h.counts.attention).padEnd(11)} ${String(h.counts.start).padEnd(9)} ${h.total}`);
+    }
+    if (selected.size > 0) {
+        console.log(`\n  * = selected`);
+    }
+});
+hero
+    .command('show')
+    .description('Show current hero preference')
+    .action(() => {
+    const config = readConfig();
+    if (config.heroes.length === 0) {
+        console.log('No hero preference set (using all heroes)');
+    }
+    else {
+        console.log(`Current heroes: ${config.heroes.join(', ')}`);
+    }
+});
+hero
+    .command('clear')
+    .description('Clear hero preference (use all heroes)')
+    .action(() => {
+    writeConfig({ heroes: [] });
+    console.log('Hero preference cleared (using all heroes)');
+});
+// ── parse ────────────────────────────────────────────────────────────
+export { program };
+if (!process.env['VITEST']) {
+    program.parse();
+}

package/dist/codex-hooks.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Get the path to Codex's config file.
+ */
+export declare function getCodexConfigPath(): string;
+/**
+ * Get the path to Codex's legacy hooks file.
+ */
+export declare function getCodexHooksPath(): string;
+/**
+ * Check if Codex config directory exists.
+ */
+export declare function isCodexAvailable(): boolean;
+/**
+ * Install Codex notifications into ~/.codex/config.toml.
+ * Current Codex exposes only the external notify command and only emits
+ * agent-turn-complete, so we install a single notify handler for success sounds.
+ */
+export declare function installCodexNotify(playScriptPath: string): void;
+/**
+ * Remove all dota2-code-sounds Codex config from config.toml and clean up
+ * legacy hooks.json installs from older versions.
+ */
+export declare function uninstallCodexNotify(): void;