@settinghead/voxlert 0.3.5

package/src/tts-test.js

@@ -0,0 +1,243 @@
+import { writeFileSync, unlinkSync, existsSync } from "fs";
+import { join } from "path";
+import { request as httpsRequest } from "https";
+import { request as httpRequest } from "http";
+import confirm from "@inquirer/confirm";
+import select from "@inquirer/select";
+import { playFile } from "./audio.js";
+import { loadPack } from "./packs.js";
+import { CACHE_DIR } from "./paths.js";
+import { printStatus, printSuccess, printWarning } from "./setup-ui.js";
+
+const TTS_TEST_PHRASE = "Voxlert TTS check. If you hear this voice, your setup is working.";
+
+export const QWEN_DOCS_URL = "https://github.com/settinghead/voxlert/blob/main/qwen3-tts-server/README.md";
+export const CHATTERBOX_DOCS_URL = "https://github.com/settinghead/voxlert/blob/main/docs/chatterbox-tts.md";
+
+function getRequestFunction(url) {
+  const urlObj = new URL(url);
+  return urlObj.protocol === "https:" ? httpsRequest : httpRequest;
+}
+
+function getTtsEndpoint(config, backend) {
+  const base = backend === "qwen"
+    ? (config.qwen_tts_url || "http://localhost:8100")
+    : (config.chatterbox_url || "http://localhost:8004");
+  return `${base}/tts`;
+}
+
+export function getTtsDocsUrl(backend) {
+  return backend === "qwen" ? QWEN_DOCS_URL : CHATTERBOX_DOCS_URL;
+}
+
+export function getTtsLabel(backend) {
+  return backend === "qwen" ? "Qwen TTS" : "Chatterbox";
+}
+
+export function getTtsChoices(currentBackend) {
+  return [
+    {
+      name: currentBackend === "qwen"
+        ? "Qwen TTS (recommended, current, more natural voice, port 8100)"
+        : "Qwen TTS (recommended, more natural voice, port 8100)",
+      value: "qwen",
+    },
+    {
+      name: currentBackend === "chatterbox"
+        ? "Chatterbox (current, port 8004)"
+        : "Chatterbox (port 8004)",
+      value: "chatterbox",
+    },
+  ];
+}
+
+export function probeTtsBackend(config, backend, timeoutMs = 2000) {
+  return new Promise((resolve) => {
+    const healthUrl = backend === "qwen"
+      ? `${config.qwen_tts_url || "http://localhost:8100"}/health`
+      : `${config.chatterbox_url || "http://localhost:8004"}/health`;
+
+    let urlObj;
+    try {
+      urlObj = new URL(healthUrl);
+    } catch {
+      return resolve(false);
+    }
+
+    const reqFn = urlObj.protocol === "https:" ? httpsRequest : httpRequest;
+    const req = reqFn(urlObj, { method: "GET", timeout: timeoutMs }, (res) => {
+      res.resume();
+      resolve(true);
+    });
+    req.on("error", () => resolve(false));
+    req.on("timeout", () => {
+      req.destroy();
+      resolve(false);
+    });
+    req.end();
+  });
+}
+
+function requestTtsAudio(config, backend, pack) {
+  return new Promise((resolve) => {
+    const endpoint = getTtsEndpoint(config, backend);
+    const body = backend === "qwen"
+      ? { text: TTS_TEST_PHRASE, pack_id: pack.id || "_default" }
+      : {
+          text: TTS_TEST_PHRASE,
+          voice_mode: "predefined",
+          predefined_voice_id: pack.voicePath || config.voice || "default.wav",
+          output_format: "wav",
+          ...(pack.tts_params || {}),
+        };
+    const payload = JSON.stringify(body);
+
+    let reqFn;
+    try {
+      reqFn = getRequestFunction(endpoint);
+    } catch {
+      return resolve(null);
+    }
+
+    const req = reqFn(
+      endpoint,
+      {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "Content-Length": Buffer.byteLength(payload),
+        },
+        timeout: backend === "qwen" ? 30000 : 8000,
+      },
+      (res) => {
+        if (res.statusCode < 200 || res.statusCode >= 300) {
+          res.resume();
+          return resolve(null);
+        }
+        const chunks = [];
+        res.on("data", (chunk) => chunks.push(chunk));
+        res.on("end", () => resolve(Buffer.concat(chunks)));
+        res.on("error", () => resolve(null));
+      },
+    );
+
+    req.on("error", () => resolve(null));
+    req.on("timeout", () => {
+      req.destroy();
+      resolve(null);
+    });
+    req.write(payload);
+    req.end();
+  });
+}
+
+export async function runTtsSample(config, backend) {
+  const pack = loadPack(config);
+  const outPath = join(CACHE_DIR, `setup-tts-test-${Date.now()}.wav`);
+
+  try {
+    const audio = await requestTtsAudio(config, backend, pack);
+    if (!audio || audio.length === 0) {
+      return false;
+    }
+    writeFileSync(outPath, audio);
+    await playFile(outPath, config.volume ?? 0.5);
+    return true;
+  } catch {
+    return false;
+  } finally {
+    if (existsSync(outPath)) {
+      try {
+        unlinkSync(outPath);
+      } catch {
+        // ignore cleanup failures
+      }
+    }
+  }
+}
+
+export async function chooseTtsBackend(config, { qwenUp, chatterboxUp }) {
+  if (qwenUp && chatterboxUp) {
+    return select({
+      message: "Both TTS servers detected. Which one to use? Qwen TTS is recommended for a more natural voice.",
+      choices: getTtsChoices(config.tts_backend),
+      default: config.tts_backend || "qwen",
+    });
+  }
+
+  if (qwenUp) {
+    printSuccess("Using Qwen TTS.");
+    return "qwen";
+  }
+
+  if (chatterboxUp) {
+    printSuccess("Using Chatterbox.");
+    return "chatterbox";
+  }
+
+  return select({
+    message: "Choose the TTS backend you are setting up. Qwen TTS is recommended for a more natural voice.",
+    choices: getTtsChoices(config.tts_backend),
+    default: config.tts_backend || "qwen",
+  });
+}
+
+export async function verifyTtsSetup(config, backend) {
+  const label = getTtsLabel(backend);
+  const docsUrl = getTtsDocsUrl(backend);
+
+  while (true) {
+    console.log("");
+    process.stdout.write(`  Checking ${label}... `);
+    const backendUp = await probeTtsBackend(config, backend);
+    console.log(backendUp ? "detected!" : "not running");
+
+    if (!backendUp) {
+      printWarning(`${label} is not running yet. Finish that setup and come back here to try again.`);
+      printStatus(`${label} docs`, docsUrl);
+      console.log("");
+      await confirm({
+        message: `Press enter after ${label} is running to test again.`,
+        default: true,
+      });
+      continue;
+    }
+
+    process.stdout.write(`  Testing ${label} audio... `);
+    const ok = await runTtsSample(config, backend);
+    console.log(ok ? "played." : "failed.");
+
+    if (!ok) {
+      printWarning(`The ${label} test failed. Keep the docs open, fix the server, and try again.`);
+      printStatus(`${label} docs`, docsUrl);
+      console.log("");
+      await confirm({
+        message: `Press enter to retry the ${label} test.`,
+        default: true,
+      });
+      continue;
+    }
+
+    const heardVoice = await select({
+      message: `Did you hear the ${label} voice test?`,
+      choices: [
+        { name: "Yes", value: true },
+        { name: "No", value: false },
+      ],
+      default: true,
+    });
+
+    if (heardVoice) {
+      printSuccess(`${label} verified.`);
+      return;
+    }
+
+    printWarning("No workaround here. Keep troubleshooting and retry until you hear the voice.");
+    printStatus(`${label} docs`, docsUrl);
+    console.log("");
+    await confirm({
+      message: "Press enter to play the test again.",
+      default: true,
+    });
+  }
+}

package/src/upgrade-check.js

@@ -0,0 +1,137 @@
+/**
+ * Upgrade check: fetch latest version from npm registry and show a terminal notification
+ * when a newer version is available. Uses a cache file to avoid hitting the registry every run.
+ */
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from "fs";
+import { join } from "path";
+import { STATE_DIR } from "./paths.js";
+
+const NPM_REGISTRY = "https://registry.npmjs.org";
+const CACHE_FILE = join(STATE_DIR, "upgrade-check.json");
+const CACHE_TTL_MS = 24 * 60 * 60 * 1000; // 24 hours
+
+/** Parse "x.y.z" into [x, y, z]; non-numeric parts become 0. */
+function parseVersion(v) {
+  const parts = String(v).split(".").map((n) => parseInt(n, 10) || 0);
+  return [parts[0] || 0, parts[1] || 0, parts[2] || 0];
+}
+
+/** True if latest > current (semver-ish). */
+function isNewer(latest, current) {
+  const [lMajor, lMinor, lPatch] = parseVersion(latest);
+  const [cMajor, cMinor, cPatch] = parseVersion(current);
+  if (lMajor !== cMajor) return lMajor > cMajor;
+  if (lMinor !== cMinor) return lMinor > cMinor;
+  return lPatch > cPatch;
+}
+
+/**
+ * Fetch latest version from npm registry.
+ * @param {string} packageName - e.g. "@settinghead/voxlert"
+ * @returns {{ latest: string } | null}
+ */
+async function fetchLatestVersion(packageName) {
+  try {
+    const url = `${NPM_REGISTRY}/${encodeURIComponent(packageName)}`;
+    const res = await fetch(url, { signal: AbortSignal.timeout(5000) });
+    if (!res.ok) return null;
+    const data = await res.json();
+    const latest = data["dist-tags"]?.latest;
+    return typeof latest === "string" ? { latest } : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Get upgrade info: use cache if fresh, else fetch from registry.
+ * @param {string} currentVersion - e.g. "0.3.2"
+ * @param {string} packageName - e.g. "@settinghead/voxlert"
+ * @returns {Promise<{ current: string, latest: string } | null>} null if no upgrade or error
+ */
+export async function getUpgradeInfo(currentVersion, packageName) {
+  const now = Date.now();
+  let latest = null;
+
+  if (existsSync(CACHE_FILE)) {
+    try {
+      const cache = JSON.parse(readFileSync(CACHE_FILE, "utf-8"));
+      if (now - (cache.checkedAt || 0) < CACHE_TTL_MS && cache.latest)
+        latest = cache.latest;
+    } catch {}
+  }
+
+  if (latest === null) {
+    const result = await fetchLatestVersion(packageName);
+    if (!result) return null;
+    latest = result.latest;
+    try {
+      mkdirSync(STATE_DIR, { recursive: true });
+      writeFileSync(
+        CACHE_FILE,
+        JSON.stringify({ latest, checkedAt: now }),
+        "utf-8"
+      );
+    } catch {}
+  }
+
+  if (!isNewer(latest, currentVersion)) return null;
+  return { current: currentVersion, latest };
+}
+
+/** ANSI codes for terminal styling (no-op when not TTY). */
+const ansi = {
+  reset: "\x1b[0m",
+  bold: "\x1b[1m",
+  dim: "\x1b[2m",
+  cyan: "\x1b[36m",
+  yellow: "\x1b[33m",
+  white: "\x1b[37m",
+  grey: "\x1b[90m",
+};
+
+function stripAnsi(str) {
+  return str.replace(/\x1b\[[0-9;]*m/g, "");
+}
+
+/**
+ * Print upgrade notification to stdout, styled like a terminal box:
+ * dark background hint, cyan "Update available!", version range, command, release notes link.
+ * Only uses colors when stdout is TTY.
+ */
+export function printUpgradeNotification(info, options = {}) {
+  const { packageName = "@settinghead/voxlert", releaseNotesUrl } = options;
+  const useColor = process.stdout.isTTY;
+  const c = useColor ? ansi : { reset: "", bold: "", dim: "", cyan: "", yellow: "", white: "", grey: "" };
+
+  const installCmd = `npm install -g ${packageName}`;
+  const url =
+    releaseNotesUrl ||
+    `https://github.com/settinghead/voxlert/releases/latest`;
+
+  const line1 = `${c.yellow}✨${c.reset} ${c.cyan}Update available!${c.reset} ${info.current} -> ${info.latest}`;
+  const line2 = `Run ${installCmd} to update.`;
+  const line3 = "See full release notes:";
+  const line4 = `${c.cyan}${url}${c.reset}`;
+
+  const padding = 2;
+  const maxLen = Math.max(
+    stripAnsi(line1).length,
+    line2.length,
+    line3.length,
+    url.length
+  );
+  const width = maxLen + padding * 2;
+  const border = "─".repeat(width);
+  const pad = (s) => " ".repeat(Math.max(0, width - 2 - stripAnsi(s).length));
+
+  console.log("");
+  console.log(`${c.grey}┌${border}┐${c.reset}`);
+  console.log(`${c.grey}│${c.reset}${" ".repeat(padding)}${line1}${pad(line1)}${c.grey}│${c.reset}`);
+  console.log(`${c.grey}│${c.reset}${" ".repeat(padding)}${line2}${pad(line2)}${c.grey}│${c.reset}`);
+  console.log(`${c.grey}│${c.reset}${" ".repeat(padding)}${line3}${pad(line3)}${c.grey}│${c.reset}`);
+  console.log(`${c.grey}│${c.reset}${" ".repeat(padding)}${line4}${pad(line4)}${c.grey}│${c.reset}`);
+  console.log(`${c.grey}└${border}┘${c.reset}`);
+  console.log("");
+}

package/src/voxlert.js

@@ -0,0 +1,200 @@
+#!/usr/bin/env node
+/**
+ * Voxlert - Game character voice notifications for Claude Code.
+ *
+ * Generates contextual 2-8 word phrases via OpenRouter LLM,
+ * speaks them through a local Chatterbox TTS server.
+ */
+
+import { basename } from "path";
+import { appendFileSync, mkdirSync } from "fs";
+import { loadConfig, EVENT_MAP, CONTEXTUAL_EVENTS, FALLBACK_PHRASES } from "./config.js";
+import { extractContext, generatePhrase } from "./llm.js";
+import { speakPhrase } from "./audio.js";
+import { showOverlay } from "./overlay.js";
+import { loadPack } from "./packs.js";
+import { STATE_DIR, LOG_FILE, HOOK_DEBUG_LOG } from "./paths.js";
+import { appendLog } from "./activity-log.js";
+
+function debugLog(msg, data) {
+  try {
+    mkdirSync(STATE_DIR, { recursive: true });
+    const line = data !== undefined
+      ? `[${new Date().toISOString()}] ${msg} ${JSON.stringify(data)}\n`
+      : `[${new Date().toISOString()}] ${msg}\n`;
+    appendFileSync(HOOK_DEBUG_LOG, line);
+  } catch {
+    // best-effort
+  }
+}
+
+function logFallback(eventName, reason, detail) {
+  try {
+    mkdirSync(STATE_DIR, { recursive: true });
+    const ts = new Date().toISOString();
+    const line = detail
+      ? `[${ts}] event=${eventName} reason=${reason} detail=${typeof detail === "string" ? detail : JSON.stringify(detail)}\n`
+      : `[${ts}] event=${eventName} reason=${reason}\n`;
+    appendFileSync(LOG_FILE, line);
+  } catch {
+    // best-effort logging
+  }
+}
+
+/**
+ * Process a hook event from parsed JSON input.
+ * Exported so it can be called from the CLI `voxlert hook` command.
+ */
+export async function processHookEvent(eventData) {
+  const source = eventData.source || "claude";
+  debugLog("processHookEvent entered", { source, hook_event_name: eventData.hook_event_name, cwd: eventData.cwd });
+  const cwd = eventData.cwd || "";
+  const config = loadConfig(cwd || undefined);
+  debugLog("processHookEvent config loaded", {
+    source,
+    cwd,
+    enabled: config.enabled !== false,
+    active_pack: config.active_pack || "",
+    llm_backend: config.llm_backend || "",
+    tts_backend: config.tts_backend || "",
+    overlay: config.overlay === true,
+    prefix: config.prefix !== undefined ? config.prefix : "${dirname}",
+    task_complete_enabled: config.categories?.["task.complete"] !== false,
+    task_error_enabled: config.categories?.["task.error"] !== false,
+  });
+  if (config.enabled === false) {
+    debugLog("processHookEvent skip: config.enabled === false", { source });
+    return;
+  }
+
+  const eventName = eventData.hook_event_name || "";
+  const category = EVENT_MAP[eventName];
+  if (!category) {
+    debugLog("processHookEvent skip: no category for event", { source, eventName });
+    return;
+  }
+
+  // Check source-specific overrides (config.sources.<source>.enabled / .categories)
+  const sourceOverride = (config.sources || {})[source] || {};
+  if (sourceOverride.enabled === false) {
+    debugLog("processHookEvent skip: source disabled", { source });
+    return;
+  }
+
+  // Check if category is enabled (source-specific categories take precedence)
+  const categories = { ...(config.categories || {}), ...(sourceOverride.categories || {}) };
+  if (categories[category] === false) {
+    debugLog("processHookEvent skip: category disabled", { source, category });
+    return;
+  }
+
+  debugLog("processHookEvent processing", { source, eventName, category });
+  // Load active voice pack
+  const pack = loadPack(config);
+  const projectName = cwd ? basename(cwd) : "";
+
+  // For contextual events, try LLM phrase generation
+  let phrase = null;
+  let fallbackReason = null;
+  let fallbackDetail = null;
+  if (CONTEXTUAL_EVENTS.has(eventName)) {
+    const context = extractContext(eventData);
+    debugLog("processHookEvent context extracted", {
+      source,
+      eventName,
+      hasContext: Boolean(context),
+      contextPreview: context ? context.replace(/\s+/g, " ").slice(0, 160) : "",
+    });
+    if (context) {
+      const result = await generatePhrase(context, config, pack.style, pack.llm_temperature, pack.examples);
+      phrase = result.phrase;
+      fallbackReason = result.fallbackReason;
+      fallbackDetail = result.detail || null;
+      if (phrase) {
+        debugLog("processHookEvent generated phrase", {
+          source,
+          eventName,
+          phrase: phrase.replace(/\s+/g, " ").slice(0, 160),
+        });
+      } else {
+        debugLog("processHookEvent generation fell back", {
+          source,
+          eventName,
+          fallbackReason,
+          fallbackDetail,
+        });
+      }
+    } else {
+      fallbackReason = "no_context";
+    }
+  }
+
+  // Fall back to predefined phrases (pack overrides defaults)
+  if (!phrase) {
+    debugLog("processHookEvent using fallback phrase", {
+      source,
+      eventName,
+      fallbackReason,
+      fallbackDetail,
+    });
+    if (fallbackReason && config.error_log === true) {
+      logFallback(eventName, fallbackReason, fallbackDetail);
+    }
+    const fallbackSource = pack.fallback_phrases || FALLBACK_PHRASES;
+    const phrases = fallbackSource[category] || ["Standing by"];
+    phrase = phrases[Math.floor(Math.random() * phrases.length)];
+  }
+
+  // Prepend prefix (supports ${dirname} template variable)
+  const prefixTemplate = config.prefix !== undefined ? config.prefix : "${dirname}";
+  let resolvedPrefix = "";
+  if (prefixTemplate !== "") {
+    resolvedPrefix = prefixTemplate.replace(/\$\{dirname\}/g, projectName);
+    if (resolvedPrefix) {
+      phrase = `${resolvedPrefix}; ${phrase}`;
+    }
+  }
+
+  const packId = config.active_pack || "sc2-adjutant";
+  const phraseOneLine = phrase.replace(/\s+/g, " ").slice(0, 120);
+  debugLog("processHookEvent speaking", { source, phrase: phraseOneLine });
+  appendLog(
+    `[${new Date().toISOString()}] source=${source} event=${eventName} category=${category} phrase=${phraseOneLine}${phrase.length > 120 ? "…" : ""}`,
+    config,
+  );
+  showOverlay(phrase, {
+    category,
+    packName: pack.name,
+    packId: pack.id || packId,
+    prefix: resolvedPrefix,
+    config,
+    overlayColors: pack.overlay_colors,
+  });
+
+  await speakPhrase(phrase, config, pack);
+  debugLog("processHookEvent done (speakPhrase returned)", { source });
+}
+
+async function main() {
+  // Read event data from stdin
+  let input = "";
+  for await (const chunk of process.stdin) {
+    input += chunk;
+  }
+
+  let eventData;
+  try {
+    eventData = JSON.parse(input);
+  } catch {
+    return;
+  }
+
+  await processHookEvent(eventData);
+}
+
+// Only run main() when this file is the entry point (not when imported by cli.js)
+const entryUrl = new URL(process.argv[1], "file://").href;
+const thisUrl = new URL(import.meta.url).href;
+if (entryUrl === thisUrl) {
+  main();
+}

package/voxlert.sh

@@ -0,0 +1,4 @@
+#!/usr/bin/env bash
+# Voxlert - Game character voice notifications for Claude Code
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+exec node "$SCRIPT_DIR/src/voxlert.js"