klaudio 0.10.2 → 0.11.0

package/bin/cli.js

@@ -7,6 +7,17 @@ if (process.argv[2] === "play") {
   process.exit(0);
 }
 
+// Subcommand: klaudio notify "title" "body"
+if (process.argv[2] === "notify") {
+  const title = process.argv[3] || "klaudio";
+  const body = process.argv[4] || "";
+  if (body) {
+    const { sendNotification } = await import("../src/notify.js");
+    await sendNotification(title, body);
+  }
+  process.exit(0);
+}
+
 // Subcommand: klaudio say "text" [--voice <voice>]
 if (process.argv[2] === "say") {
   const args = process.argv.slice(3);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "klaudio",
-  "version": "0.10.2",
+  "version": "0.11.0",
   "description": "Add sound effects to your coding sessions — play sounds when tasks complete, notifications arrive, and more",
   "type": "module",
   "bin": {
@@ -32,7 +32,6 @@
     "ink": "^6.8.0",
     "ink-select-input": "^6.2.0",
     "ink-spinner": "^5.0.0",
-    "kokoro-js": "^1.2.1",
     "react": "^19.2.4"
   },
   "engines": {

package/src/cli.js

@@ -2,10 +2,10 @@ import React, { useState, useEffect, useCallback, useRef, useMemo } from "react"
 import { render, Box, Text, useInput, useApp } from "ink";
 import Spinner from "ink-spinner";
 import { PRESETS, EVENTS } from "./presets.js";
-import { KOKORO_PRESET_VOICES, KOKORO_VOICES, KOKORO_DEFAULT_VOICE } from "./tts.js";
+import { KOKORO_PRESET_VOICES, KOKORO_VOICES, KOKORO_DEFAULT_VOICE, isKokoroAvailable } from "./tts.js";
 import { playSoundWithCancel, getWavDuration } from "./player.js";
 import { getAvailableGames, getSystemSounds } from "./scanner.js";
-import { install, uninstall, getExistingSounds } from "./installer.js";
+import { install, uninstall, getExistingSounds, checkHooksOutdated } from "./installer.js";
 import { getVgmstreamPath, findPackedAudioFiles, extractToWav } from "./extractor.js";
 import { extractUnityResource } from "./unity.js";
 import { extractBunFile, isBunFile } from "./scumm.js";
@@ -17,6 +17,17 @@ import { join } from "node:path";
 const MAX_PLAY_SECONDS = 10;
 const ACCENT = "#76C41E"; // Needle green-yellow midpoint
 
+/** Truncate a filename: keep first 10 chars + ext (max 4 chars) */
+function shortName(filePath) {
+  const name = basename(filePath);
+  const dot = name.lastIndexOf(".");
+  if (dot <= 0 || name.length <= 18) return name;
+  const stem = name.slice(0, dot);
+  const ext = name.slice(dot);
+  if (stem.length <= 10) return name;
+  return stem.slice(0, 10) + "..." + ext;
+}
+
 const h = React.createElement;
 
 // ── Custom SelectInput components (bright colors for CMD) ────
@@ -171,11 +182,14 @@ const ScopeScreen = ({ onNext, onMusic, tts, onToggleTts }) => {
 };
 
 // ── Screen: Preset ──────────────────────────────────────────────
-const PresetScreen = ({ existingSounds, onNext, onReapply, onBack }) => {
+const PresetScreen = ({ existingSounds, outdatedReasons, onNext, onReapply, onBack }) => {
   const hasExisting = existingSounds && Object.values(existingSounds).some(Boolean);
+  const isOutdated = outdatedReasons && outdatedReasons.length > 0;
   const items = [
     ...(hasExisting ? [{
-      label: "✓ Re-apply current sounds  — update config with current selections",
+      label: isOutdated
+        ? "⬆ Update hooks  — new features available for your current sounds"
+        : "✓ Re-apply current sounds  — update config with current selections",
       value: "_reapply",
     }] : []),
     ...Object.entries(PRESETS).map(([id, p]) => ({
@@ -206,8 +220,16 @@ const PresetScreen = ({ existingSounds, onNext, onReapply, onBack }) => {
       ? h(Box, { flexDirection: "column", marginLeft: 4, marginBottom: 1 },
           h(Text, { dimColor: true }, "Current sounds:"),
           ...Object.entries(existingSounds).filter(([_, p]) => p).map(([eid, p]) =>
-            h(Text, { key: eid, color: "green", dimColor: true }, `  ✓ ${EVENTS[eid].name}: ${basename(p)}`),
+            h(Text, { key: eid, color: "green", dimColor: true }, `  ✓ ${EVENTS[eid].name}: ${shortName(p)}`),
           ),
+          isOutdated
+            ? h(Box, { flexDirection: "column", marginTop: 1 },
+                h(Text, { color: "yellow" }, "  Updates available:"),
+                ...outdatedReasons.map((r, i) =>
+                  h(Text, { key: i, color: "yellow", dimColor: true }, `    + ${r}`),
+                ),
+              )
+            : null,
         )
       : null,
     h(Box, { flexDirection: "column", marginLeft: 2 },
@@ -1370,11 +1392,11 @@ const ExtractingScreen = ({ game, onDone, onBack }) => {
 };
 
 // ── Screen: Confirm ─────────────────────────────────────────────
-const ConfirmScreen = ({ scope, sounds, tts, voice, onToggleTts, onCycleVoice, onConfirm, onBack }) => {
+const ConfirmScreen = ({ scope, sounds, tts, voice, hasKokoro, onToggleTts, onCycleVoice, onConfirm, onBack }) => {
   useInput((input, key) => {
     if (key.escape) onBack();
     else if (input === "t") onToggleTts();
-    else if (input === "v" && tts) onCycleVoice();
+    else if (input === "v" && tts && hasKokoro) onCycleVoice();
   });
 
   const items = [
@@ -1383,7 +1405,7 @@ const ConfirmScreen = ({ scope, sounds, tts, voice, onToggleTts, onCycleVoice, o
   ];
 
   const soundEntries = Object.entries(sounds).filter(([_, path]) => path);
-  const voiceInfo = KOKORO_VOICES.find((v) => v.id === voice);
+  const voiceInfo = hasKokoro ? KOKORO_VOICES.find((v) => v.id === voice) : null;
 
   return h(Box, { flexDirection: "column" },
     h(Text, { bold: true, marginLeft: 2 }, "  Ready to install:"),
@@ -1391,7 +1413,7 @@ const ConfirmScreen = ({ scope, sounds, tts, voice, onToggleTts, onCycleVoice, o
       h(Text, { marginLeft: 4 }, `Scope: ${scope === "global" ? "Global (Claude Code + Copilot)" : "This project (Claude Code + Copilot)"}`),
       ...soundEntries.map(([eid, path]) =>
         h(Text, { key: eid, marginLeft: 4 },
-          `${EVENTS[eid].name} → ${basename(path)}`
+          `${EVENTS[eid].name} → ${shortName(path)}`
         )
       ),
       h(Box, { marginLeft: 4, marginTop: 1 },
@@ -1530,10 +1552,16 @@ const InstallApp = () => {
   const [installResult, setInstallResult] = useState(null);
   const [tts, setTts] = useState(true);
   const [voice, setVoice] = useState(KOKORO_DEFAULT_VOICE);
+  const [hasKokoro, setHasKokoro] = useState(false);
+  const [outdatedReasons, setOutdatedReasons] = useState([]);
   const [musicFiles, setMusicFiles] = useState([]);
   const [musicGameName, setMusicGameName] = useState(null);
   const [musicShuffle, setMusicShuffle] = useState(false);
 
+  useEffect(() => {
+    isKokoroAvailable().then(setHasKokoro).catch(() => {});
+  }, []);
+
   const initSoundsFromPreset = useCallback((pid) => {
     const preset = PRESETS[pid];
     if (preset) setSounds({ ...preset.sounds });
@@ -1550,6 +1578,7 @@ const InstallApp = () => {
             getExistingSounds(s).then((existing) => {
               if (Object.keys(existing).length > 0) setSounds(existing);
             });
+            checkHooksOutdated(s).then(setOutdatedReasons).catch(() => {});
             setScreen(SCREEN.PRESET);
           },
           onMusic: () => setScreen(SCREEN.MUSIC_MODE),
@@ -1558,6 +1587,7 @@ const InstallApp = () => {
       case SCREEN.PRESET:
         return h(PresetScreen, {
           existingSounds: sounds,
+          outdatedReasons,
           onReapply: () => setScreen(SCREEN.CONFIRM),
           onNext: (id) => {
             if (id === "_music") {
@@ -1660,6 +1690,7 @@ const InstallApp = () => {
           sounds,
           tts,
           voice,
+          hasKokoro,
           onToggleTts: () => setTts((v) => !v),
           onCycleVoice: () => setVoice((v) => {
             const idx = KOKORO_VOICES.findIndex((x) => x.id === v);

package/src/installer.js

@@ -118,8 +118,8 @@ async function installApprovalHooks(settings, soundPath, claudeDir) {
   // Write the timer script
   const script = `#!/usr/bin/env bash
 # klaudio: approval notification timer
-# Plays a sound + speaks a TTS message if a tool isn't approved within DELAY seconds.
-DELAY=15
+# Plays a sound + sends a system notification if a tool isn't approved within DELAY seconds.
+DELAY=60
 MARKER="/tmp/.claude-approval-pending"
 SOUND="${normalized}"
 
@@ -135,6 +135,7 @@ case "$1" in
         PROJECT=$(tail -1 "$MARKER" 2>/dev/null | sed 's|.*[/\\\\]||')
         rm -f "$MARKER"
         npx klaudio play "$SOUND" 2>/dev/null
+        npx klaudio notify "\${PROJECT:-project}" "Waiting for your approval" 2>/dev/null
         npx klaudio say "\${PROJECT:-project} needs your attention" 2>/dev/null
       fi
     ) &
@@ -268,6 +269,58 @@ export async function getExistingSounds(scope) {
   return sounds;
 }
 
+/**
+ * Check if existing hooks are outdated (missing features from newer versions).
+ * Returns a list of reasons why hooks should be updated.
+ */
+export async function checkHooksOutdated(scope) {
+  const claudeDir = getTargetDir(scope);
+  const settingsFile = join(claudeDir, "settings.json");
+  const reasons = [];
+
+  try {
+    const existing = await readFile(settingsFile, "utf-8");
+    const settings = JSON.parse(existing);
+    if (!settings.hooks) return reasons;
+
+    // Check Stop hook for --notify flag
+    const stopEntries = settings.hooks.Stop || [];
+    const stopHook = stopEntries.find((e) => e._klaudio || e.hooks?.[0]?.command?.includes("klaudio"));
+    if (stopHook?.hooks?.[0]?.command && !stopHook.hooks[0].command.includes("--notify")) {
+      reasons.push("System notifications on task complete");
+    }
+
+    // Check Notification hook for --notify flag
+    const notifEntries = settings.hooks.Notification || [];
+    const notifHook = notifEntries.find((e) => e._klaudio || e.hooks?.[0]?.command?.includes("klaudio"));
+    if (notifHook?.hooks?.[0]?.command && !notifHook.hooks[0].command.includes("--notify")) {
+      reasons.push("System notifications on background task");
+    }
+
+    // Check approval script for notify command and timer delay
+    const scriptPath = join(claudeDir, "approval-notify.sh");
+    try {
+      const script = await readFile(scriptPath, "utf-8");
+      if (!script.includes("klaudio notify")) {
+        reasons.push("System notifications on approval wait");
+      }
+      if (script.includes("DELAY=15")) {
+        reasons.push("Approval timer too short (15s -> 60s)");
+      }
+    } catch { /* no script */ }
+
+    // Check for duplicate hooks (old bug)
+    for (const [event, entries] of Object.entries(settings.hooks)) {
+      const klaudioEntries = entries.filter((e) => e._klaudio || e._klonk);
+      if (klaudioEntries.length > 1) {
+        reasons.push(`Duplicate ${event} hooks`);
+      }
+    }
+  } catch { /* no existing config */ }
+
+  return reasons;
+}
+
 /**
  * Uninstall klaudio hooks from settings.
  */

package/src/notify.js

@@ -0,0 +1,135 @@
+import { spawn } from "node:child_process";
+import { platform } from "node:os";
+
+/**
+ * Send a native OS notification (fire-and-forget).
+ * Click-to-focus: activates the terminal or editor that triggered it.
+ *
+ * Windows: WinRT toast (Win10+), focuses Windows Terminal or VS Code on click
+ * macOS:   terminal-notifier (if installed) or osascript fallback
+ * Linux:   notify-send
+ */
+export function sendNotification(title, body) {
+  const os = platform();
+  try {
+    if (os === "win32") return notifyWindows(title, body);
+    if (os === "darwin") return notifyMac(title, body);
+    return notifyLinux(title, body);
+  } catch {
+    return Promise.resolve();
+  }
+}
+
+/**
+ * Detect the terminal/editor environment.
+ */
+function detectTerminal() {
+  const tp = process.env.TERM_PROGRAM;
+  if (tp === "vscode") return "vscode";
+  if (tp === "cursor") return "cursor";
+  if (tp === "iTerm.app") return "iterm";
+  if (tp === "Apple_Terminal") return "terminal";
+  if (process.env.WT_SESSION) return "windows-terminal";
+  // Fallback: check PATH for clues (hooks inherit the terminal's env)
+  const path = process.env.PATH || "";
+  if (/cursor[/\\]/i.test(path) && /resources[/\\]app[/\\]bin/i.test(path)) return "cursor";
+  if (/VS Code[/\\]bin/i.test(path) || /Code[/\\]bin/i.test(path)) return "vscode";
+  return "unknown";
+}
+
+function escapeXml(s) {
+  return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&apos;");
+}
+
+// ── Windows ──────────────────────────────────────────────────────
+
+function notifyWindows(title, body) {
+  const safeTitle = escapeXml(title);
+  const safeBody = escapeXml(body);
+
+  // Determine activation strategy based on the terminal we're running in
+  let toastAttrs = "";
+  let appId;
+  const terminal = detectTerminal();
+
+  if (terminal === "vscode" || terminal === "cursor") {
+    // VS Code / Cursor: use protocol handler to focus the editor on click
+    const protocol = terminal === "cursor" ? "cursor://" : "vscode://";
+    toastAttrs = ` activationType="protocol" launch="${protocol}"`;
+    appId = "klaudio";
+  } else if (terminal === "windows-terminal") {
+    // Windows Terminal: use its AUMID so clicking focuses WT
+    appId = "Microsoft.WindowsTerminal_8wekyb3d8bbwe!App";
+  } else {
+    appId = "klaudio";
+  }
+
+  const toastXml = `<toast${toastAttrs}><visual><binding template="ToastGeneric"><text>${safeTitle}</text><text>${safeBody}</text></binding></visual></toast>`;
+
+  // PowerShell script: show WinRT toast notification
+  const ps = `\
+[void][Windows.UI.Notifications.ToastNotificationManager, Windows.UI.Notifications, ContentType = WindowsRuntime]
+[void][Windows.Data.Xml.Dom.XmlDocument, Windows.Data.Xml.Dom, ContentType = WindowsRuntime]
+$x = [Windows.Data.Xml.Dom.XmlDocument]::new()
+$x.LoadXml('${toastXml.replace(/'/g, "''")}')
+$t = [Windows.UI.Notifications.ToastNotification]::new($x)
+[Windows.UI.Notifications.ToastNotificationManager]::CreateToastNotifier('${appId}').Show($t)`;
+
+  // Run detached so the Node process can exit immediately
+  const child = spawn("powershell.exe", ["-NoProfile", "-NonInteractive", "-Command", ps], {
+    windowsHide: true,
+    detached: true,
+    stdio: "ignore",
+  });
+  child.unref();
+  return Promise.resolve();
+}
+
+// ── macOS ────────────────────────────────────────────────────────
+
+function notifyMac(title, body) {
+  // Determine which app to activate when the notification is clicked
+  const terminal = detectTerminal();
+  const bundleIds = {
+    vscode: "com.microsoft.VSCode",
+    cursor: "com.todesktop.230313mzl4w4u92",
+    iterm: "com.googlecode.iterm2",
+    terminal: "com.apple.Terminal",
+  };
+  const bundleId = bundleIds[terminal] || "com.apple.Terminal";
+
+  // Try terminal-notifier first (best UX: click-to-focus), fall back to osascript
+  return new Promise((resolve) => {
+    const child = spawn("terminal-notifier", [
+      "-title", title, "-message", body,
+      "-activate", bundleId, "-sender", bundleId,
+      "-sound", "default",
+    ], { stdio: "ignore", timeout: 10000 });
+
+    child.on("error", () => {
+      // terminal-notifier not installed — fall back to osascript
+      const safeTitle = title.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+      const safeBody = body.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+      const script = `display notification "${safeBody}" with title "${safeTitle}"`;
+      const child2 = spawn("osascript", ["-e", script], {
+        stdio: "ignore",
+        detached: true,
+      });
+      child2.unref();
+      resolve();
+    });
+
+    child.on("close", () => resolve());
+  });
+}
+
+// ── Linux ────────────────────────────────────────────────────────
+
+function notifyLinux(title, body) {
+  const child = spawn("notify-send", ["-a", "klaudio", title, body], {
+    stdio: "ignore",
+    detached: true,
+  });
+  child.unref();
+  return Promise.resolve();
+}

package/src/player.js

@@ -386,6 +386,30 @@ export async function handlePlayCommand(args) {
     if (stdinData.trim()) hookData = JSON.parse(stdinData);
   } catch { /* no stdin or invalid JSON */ }
 
+  const notify = args.includes("--notify");
+
+  // Send system notification (detached, never blocks)
+  if (notify) {
+    const project = hookData.cwd ? hookData.cwd.replace(/\\/g, "/").split("/").pop() : null;
+    const notifTitle = project || "klaudio";
+    let notifBody = "Task complete";
+    if (hookData.last_assistant_message) {
+      // Extract first sentence for the notification body
+      const plain = hookData.last_assistant_message
+        .replace(/```[\s\S]*?```/g, "").replace(/`([^`]+)`/g, "$1")
+        .replace(/\*\*([^*]+)\*\*/g, "$1").replace(/\*([^*]+)\*/g, "$1")
+        .replace(/#{1,6}\s+/g, "").replace(/\[([^\]]+)\]\([^)]+\)/g, "$1")
+        .replace(/\([^)]*\)/g, "").replace(/\n+/g, " ").trim();
+      const first = plain.match(/^[^.!?]*[.!?]/)?.[0] || plain.slice(0, 120);
+      notifBody = first.trim();
+    } else if (hookData.message) {
+      notifBody = hookData.message.slice(0, 120);
+    }
+    import("./notify.js").then(({ sendNotification }) =>
+      sendNotification(notifTitle, notifBody)
+    ).catch(() => {});
+  }
+
   // Play sound (fire and forget, don't wait)
   const soundPromise = soundFile
     ? playSoundWithCancel(soundFile).promise.catch(() => {})
@@ -455,9 +479,10 @@ export async function handlePlayCommand(args) {
 /**
  * Generate the shell command string for use in Claude Code hooks.
  */
-export function getHookPlayCommand(soundFilePath, { tts = false, voice } = {}) {
+export function getHookPlayCommand(soundFilePath, { tts = false, voice, notify = true } = {}) {
   const normalized = soundFilePath.replace(/\\/g, "/");
   const ttsFlag = tts ? " --tts" : "";
   const voiceFlag = tts && voice ? ` --voice ${voice}` : "";
-  return `npx klaudio play "${normalized}"${ttsFlag}${voiceFlag}`;
+  const notifyFlag = notify ? " --notify" : "";
+  return `npx klaudio play "${normalized}"${ttsFlag}${voiceFlag}${notifyFlag}`;
 }

package/src/tts.js

@@ -40,17 +40,80 @@ const KOKORO_VOICES = [
 // Singleton: reuse the loaded model across calls
 let kokoroInstance = null;
 let kokoroLoadPromise = null;
+const KOKORO_DIR = join(homedir(), ".klaudio", "kokoro");
 
 /**
- * Load the Kokoro TTS model (singleton, downloads ~86MB on first use).
- * Uses CPU backend (DirectML has ConvTranspose compatibility issues).
+ * Ensure kokoro-js is installed in ~/.klaudio/kokoro.
+ * Installs on first use via npm.
+ */
+async function ensureKokoroInstalled() {
+  const kokoroMod = join(KOKORO_DIR, "node_modules", "kokoro-js");
+  try {
+    await stat(join(kokoroMod, "package.json"));
+    return; // already installed
+  } catch { /* needs install */ }
+
+  await mkdir(KOKORO_DIR, { recursive: true });
+  await fsWriteFile(join(KOKORO_DIR, "package.json"), '{"private":true}', "utf-8");
+
+  const npmCmd = platform() === "win32" ? "npm.cmd" : "npm";
+  await new Promise((resolve, reject) => {
+    execFile(npmCmd, ["install", "kokoro-js"], {
+      cwd: KOKORO_DIR,
+      windowsHide: true,
+      timeout: 180000,
+    }, (err) => err ? reject(err) : resolve());
+  });
+}
+
+/**
+ * Check if kokoro-js is available without loading the model.
+ */
+export async function isKokoroAvailable() {
+  try {
+    await importKokoro();
+    return true;
+  } catch { return false; }
+}
+
+/**
+ * Try to import kokoro-js from various locations.
+ */
+async function importKokoro() {
+  // 1. Try local ~/.klaudio/kokoro install
+  try {
+    const { createRequire } = await import("node:module");
+    const req = createRequire(join(KOKORO_DIR, "node_modules", "kokoro-js", "package.json"));
+    return req("kokoro-js");
+  } catch { /* not there */ }
+
+  // 2. Try global/project import (dev environment or globally installed)
+  try {
+    return await import("kokoro-js");
+  } catch { /* not available */ }
+
+  throw new Error("kokoro-js not available");
+}
+
+/**
+ * Load the Kokoro TTS model (singleton).
+ * Auto-installs kokoro-js on first use, then downloads ~25MB model on first generate.
  */
 async function getKokoro() {
   if (kokoroInstance) return kokoroInstance;
   if (kokoroLoadPromise) return kokoroLoadPromise;
 
   kokoroLoadPromise = (async () => {
-    const { KokoroTTS } = await import("kokoro-js");
+    // Try import first (already installed?), otherwise install then import
+    let mod;
+    try {
+      mod = await importKokoro();
+    } catch {
+      await ensureKokoroInstalled();
+      mod = await importKokoro();
+    }
+
+    const { KokoroTTS } = mod;
     kokoroInstance = await KokoroTTS.from_pretrained(
       "onnx-community/Kokoro-82M-v1.0-ONNX",
       { dtype: "q4", device: "cpu" },