@settinghead/voxlert 0.3.5

package/src/overlay.jxa

@@ -0,0 +1,186 @@
+/**
+ * Voxlert — Native macOS overlay notification.
+ *
+ * Usage:
+ *   osascript -l JavaScript overlay.jxa <message> <gradient_json> <icon_path> <slot> <dismiss_secs> [subtitle]
+ *
+ * Arguments:
+ *   message        — Main phrase text
+ *   gradient_json  — JSON array of [r,g,b] triples (0-1), e.g. '[[0.1,0.4,0.7],[0.05,0.2,0.5]]'
+ *   icon_path      — Absolute path to character icon (or "" for no icon)
+ *   slot           — Vertical slot index (0-4)
+ *   dismiss_secs   — Seconds before auto-dismiss
+ *   subtitle       — Optional subtitle text (project name · character)
+ */
+
+ObjC.import("Cocoa");
+ObjC.import("QuartzCore");
+
+function run(argv) {
+  var message = argv[0] || "Notification";
+  var gradientJson = argv[1] || "[[0.15,0.15,0.2],[0.1,0.1,0.15]]";
+  var iconPath = argv[2] || "";
+  var slot = parseInt(argv[3], 10) || 0;
+  var dismissSecs = parseFloat(argv[4]) || 4;
+  var subtitle = argv[5] || "";
+
+  // Parse gradient colors
+  var colors;
+  try {
+    colors = JSON.parse(gradientJson);
+  } catch (e) {
+    colors = [[0.15, 0.15, 0.2], [0.1, 0.1, 0.15]];
+  }
+
+  // Ensure we have at least 2 color stops
+  if (!Array.isArray(colors) || colors.length < 2) {
+    colors = [[0.15, 0.15, 0.2], [0.1, 0.1, 0.15]];
+  }
+
+  // Window dimensions
+  var winWidth = 500;
+  var winHeight = 80;
+  var cornerRadius = 12;
+  var iconSize = 48;
+  var iconPadding = 16;
+
+  // Get screen geometry
+  var screen = $.NSScreen.mainScreen;
+  var frame = screen.visibleFrame;
+  var screenWidth = frame.size.width;
+  var screenTop = frame.origin.y + frame.size.height;
+
+  // Position: top-center, stacked by slot
+  var x = (screenWidth - winWidth) / 2 + frame.origin.x;
+  var slotGap = winHeight + 8;
+  var y = screenTop - winHeight - 12 - (slot * slotGap);
+
+  // Create borderless, always-on-top window
+  var winRect = $.NSMakeRect(x, y, winWidth, winHeight);
+  var styleMask = $.NSWindowStyleMaskBorderless;
+  var win = $.NSWindow.alloc.initWithContentRectStyleMaskBackingDefer(
+    winRect, styleMask, $.NSBackingStoreBuffered, false
+  );
+  win.setLevel($.NSStatusWindowLevel + 1);
+  win.setOpaque(false);
+  win.setAlphaValue(0.95);
+  win.setBackgroundColor($.NSColor.clearColor);
+  win.setHasShadow(true);
+  win.setIgnoresMouseEvents(true);
+
+  // Content view with rounded corners
+  var contentView = win.contentView;
+  contentView.wantsLayer = true;
+  var layer = contentView.layer;
+  layer.cornerRadius = cornerRadius;
+  layer.masksToBounds = true;
+
+  // Animated gradient background
+  var gradientLayer = $.CAGradientLayer.layer;
+  gradientLayer.frame = layer.bounds;
+
+  // Build NSColor array for gradient
+  var nsColors = $.NSMutableArray.alloc.init;
+  for (var i = 0; i < colors.length; i++) {
+    var c = colors[i];
+    var r = c[0] || 0, g = c[1] || 0, b = c[2] || 0;
+    var nsColor = $.NSColor.colorWithCalibratedRedGreenBlueAlpha(r, g, b, 1.0);
+    nsColors.addObject(nsColor.CGColor);
+  }
+  gradientLayer.colors = nsColors;
+  gradientLayer.startPoint = $.CGPointMake(0, 0);
+  gradientLayer.endPoint = $.CGPointMake(1, 1);
+  layer.insertSublayerAtIndex(gradientLayer, 0);
+
+  // Animate gradient flow
+  var anim = $.CABasicAnimation.animationWithKeyPath("startPoint");
+  anim.fromValue = $.NSValue.valueWithPoint($.NSMakePoint(0, 0));
+  anim.toValue = $.NSValue.valueWithPoint($.NSMakePoint(1, 0));
+  anim.duration = 3.0;
+  anim.repeatCount = Infinity;
+  anim.autoreverses = true;
+  gradientLayer.addAnimationForKey(anim, "flowStart");
+
+  var anim2 = $.CABasicAnimation.animationWithKeyPath("endPoint");
+  anim2.fromValue = $.NSValue.valueWithPoint($.NSMakePoint(1, 1));
+  anim2.toValue = $.NSValue.valueWithPoint($.NSMakePoint(0, 1));
+  anim2.duration = 3.0;
+  anim2.repeatCount = Infinity;
+  anim2.autoreverses = true;
+  gradientLayer.addAnimationForKey(anim2, "flowEnd");
+
+  // Text area offset (shift right if icon present)
+  var textLeft = iconPadding;
+  var hasIcon = false;
+
+  // Character icon
+  if (iconPath && iconPath !== "") {
+    var img = $.NSImage.alloc.initWithContentsOfFile($(iconPath));
+    if (img && img.isValid) {
+      hasIcon = true;
+      var imgView = $.NSImageView.alloc.initWithFrame(
+        $.NSMakeRect(iconPadding, (winHeight - iconSize) / 2, iconSize, iconSize)
+      );
+      imgView.setImage(img);
+      imgView.setImageScaling($.NSImageScaleProportionallyUpOrDown);
+      contentView.addSubview(imgView);
+      textLeft = iconPadding + iconSize + 12;
+    }
+  }
+
+  var textWidth = winWidth - textLeft - iconPadding;
+
+  // Main phrase text (bold 16pt, white)
+  var phraseLabel = $.NSTextField.alloc.initWithFrame(
+    $.NSMakeRect(textLeft, subtitle ? 28 : 22, textWidth, 30)
+  );
+  phraseLabel.stringValue = $(message);
+  phraseLabel.bezeled = false;
+  phraseLabel.drawsBackground = false;
+  phraseLabel.editable = false;
+  phraseLabel.selectable = false;
+  phraseLabel.textColor = $.NSColor.whiteColor;
+  phraseLabel.font = $.NSFont.boldSystemFontOfSize(16);
+  phraseLabel.lineBreakMode = $.NSLineBreakByTruncatingTail;
+  contentView.addSubview(phraseLabel);
+
+  // Subtitle (12pt, white 70% opacity)
+  if (subtitle) {
+    var subLabel = $.NSTextField.alloc.initWithFrame(
+      $.NSMakeRect(textLeft, 10, textWidth, 20)
+    );
+    subLabel.stringValue = $(subtitle);
+    subLabel.bezeled = false;
+    subLabel.drawsBackground = false;
+    subLabel.editable = false;
+    subLabel.selectable = false;
+    subLabel.textColor = $.NSColor.colorWithCalibratedRedGreenBlueAlpha(1, 1, 1, 0.7);
+    subLabel.font = $.NSFont.systemFontOfSize(12);
+    subLabel.lineBreakMode = $.NSLineBreakByTruncatingTail;
+    contentView.addSubview(subLabel);
+  }
+
+  // Show window (skip NSViewAnimation fade-in — in JXA the animation target can be lost/bridge as null)
+  win.setAlphaValue(0.95);
+  win.orderFrontRegardless;
+
+  var app = $.NSApplication.sharedApplication;
+  app.activateIgnoringOtherApps(false);
+
+  // Run loop with timeout
+  var runLoop = $.NSRunLoop.currentRunLoop;
+  var endDate = $.NSDate.dateWithTimeIntervalSinceNow(dismissSecs);
+  while (runLoop.runModeBeforeDate($.NSDefaultRunLoopMode, endDate)) {
+    if ($.NSDate.date.compare(endDate) !== $.NSOrderedAscending) break;
+  }
+
+  // Fade out by animating alpha (avoids NSViewAnimation null-target issue in JXA)
+  var fadeOutEnd = $.NSDate.dateWithTimeIntervalSinceNow(0.35);
+  for (var a = 0.95; a > 0; a -= 0.15) {
+    win.setAlphaValue(Math.max(0, a));
+    runLoop.runModeBeforeDate($.NSDefaultRunLoopMode, $.NSDate.dateWithTimeIntervalSinceNow(0.05));
+  }
+  win.setAlphaValue(0);
+
+  win.close;
+}

package/src/pack-registry.js

@@ -0,0 +1,28 @@
+/**
+ * Registry of voice packs that can be downloaded from the GitHub repo.
+ * Used by the setup wizard so users can choose which packs to install
+ * without shipping them all in the npm package.
+ *
+ * baseUrl should point at raw GitHub content (branch or tag).
+ */
+
+const GITHUB_RAW_BASE = "https://raw.githubusercontent.com/settinghead/voxlert/main/packs";
+
+export const PACK_REGISTRY = [
+  { id: "sc2-adjutant", name: "StarCraft 2 Adjutant" },
+  { id: "sc1-adjutant", name: "StarCraft 1 Adjutant" },
+  { id: "red-alert-eva", name: "Red Alert EVA" },
+  { id: "sc1-kerrigan", name: "SC1 Kerrigan" },
+  { id: "sc2-kerrigan", name: "SC2 Kerrigan" },
+  { id: "sc1-protoss-advisor", name: "Protoss Advisor (SC1)" },
+  { id: "sc2-protoss-advisor", name: "Protoss Advisor (SC2)" },
+  { id: "ss1-shodan", name: "SHODAN" },
+  { id: "hl-hev-suit", name: "HEV Suit" },
+];
+
+/** Default pack ids to pre-select in setup when offering download. */
+export const DEFAULT_DOWNLOAD_PACK_IDS = ["sc2-adjutant", "sc1-adjutant", "red-alert-eva"];
+
+export function getPackRegistryBaseUrl() {
+  return process.env.VOXLERT_PACKS_BASE_URL || GITHUB_RAW_BASE;
+}

package/src/packs.js

@@ -0,0 +1,182 @@
+import { readFileSync, writeFileSync, readdirSync, existsSync, mkdirSync, statSync } from "fs";
+import { join, resolve } from "path";
+import { execSync } from "child_process";
+import { createHash } from "crypto";
+import { PACKS_DIR, PACK_VOLUME_CACHE_DIR } from "./paths.js";
+
+// Target mean volume in dBFS — voices are normalized to this level
+const TARGET_MEAN_DB = -16;
+
+/**
+ * Analyze a WAV file's mean volume using ffmpeg volumedetect.
+ * Returns mean_volume in dBFS, or null on failure.
+ */
+function analyzeVolume(wavPath) {
+  try {
+    const output = execSync(
+      `ffmpeg -i "${wavPath}" -af volumedetect -f null /dev/null 2>&1`,
+      { encoding: "utf-8", timeout: 10000 },
+    );
+    const match = output.match(/mean_volume:\s*([-\d.]+)\s*dB/);
+    if (match) return parseFloat(match[1]);
+  } catch {
+    // ffmpeg not available or analysis failed
+  }
+  return null;
+}
+
+/**
+ * Get volume offset in dB for a pack's voice file.
+ * Caches result in ~/.voxlert/pack-volume/<pack-id>.json.
+ */
+function getVolumeOffsetDb(voicePath, packId) {
+  if (!voicePath || !existsSync(voicePath)) return 0;
+
+  let stats;
+  try {
+    stats = statSync(voicePath);
+  } catch {
+    return 0;
+  }
+
+  const voiceKey = createHash("sha1").update(voicePath).digest("hex");
+
+  // Check cache
+  const cachePath = join(PACK_VOLUME_CACHE_DIR, `${packId || "_legacy"}.json`);
+  try {
+    const cached = JSON.parse(readFileSync(cachePath, "utf-8"));
+    if (
+      cached.voiceKey === voiceKey &&
+      cached.mtimeMs === Math.round(stats.mtimeMs) &&
+      cached.size === stats.size &&
+      typeof cached.offsetDb === "number"
+    ) {
+      return cached.offsetDb;
+    }
+  } catch {
+    // no cache or invalid
+  }
+
+  // Analyze and cache
+  const meanDb = analyzeVolume(voicePath);
+  if (meanDb == null) return 0;
+
+  const offsetDb = Math.round((TARGET_MEAN_DB - meanDb) * 10) / 10;
+  try {
+    mkdirSync(PACK_VOLUME_CACHE_DIR, { recursive: true });
+    writeFileSync(
+      cachePath,
+      JSON.stringify({
+        voiceKey,
+        mtimeMs: Math.round(stats.mtimeMs),
+        size: stats.size,
+        meanDb,
+        offsetDb,
+      }) + "\n",
+    );
+  } catch {
+    // best-effort caching
+  }
+  return offsetDb;
+}
+
+/**
+ * Load a voice pack by id (from config.active_pack).
+ * Returns { id, name, echo, voicePath, style, fallback_phrases }.
+ * Falls back to legacy config.voice if no active_pack is set.
+ */
+export function loadPack(config) {
+  let packId = config.active_pack;
+
+  // Random mode: pick a random pack each time
+  if (packId === "random") {
+    const packs = listPacks();
+    if (packs.length > 0) {
+      packId = packs[Math.floor(Math.random() * packs.length)].id;
+    } else {
+      packId = null;
+    }
+  }
+
+  // Legacy fallback: no active_pack configured
+  if (!packId) {
+    return {
+      id: "_legacy",
+      name: "Legacy",
+      echo: true,
+      voicePath: config.voice || "default.wav",
+      volumeOffsetDb: 0,
+      style: null,
+      fallback_phrases: null,
+    };
+  }
+
+  const packDir = join(PACKS_DIR, packId);
+  const packJsonPath = join(packDir, "pack.json");
+
+  let packData;
+  try {
+    packData = JSON.parse(readFileSync(packJsonPath, "utf-8"));
+  } catch {
+    // Pack not found or invalid — fall back to defaults
+    return {
+      id: packId,
+      name: packId,
+      echo: true,
+      voicePath: config.voice || "default.wav",
+      volumeOffsetDb: 0,
+      style: null,
+      fallback_phrases: null,
+    };
+  }
+
+  // Resolve voice path: relative to pack dir, or fall back to config.voice
+  let voicePath = config.voice || "default.wav";
+  if (packData.voice) {
+    const resolved = resolve(packDir, packData.voice);
+    if (existsSync(resolved)) {
+      voicePath = resolved;
+    }
+  }
+
+  return {
+    id: packId,
+    name: packData.name || packId,
+    echo: packData.echo !== false,
+    voicePath,
+    volumeOffsetDb: getVolumeOffsetDb(voicePath, packId),
+    tts_params: packData.tts_params || null,
+    audio_filter: packData.audio_filter || null,
+    post_process: packData.post_process || null,
+    style: packData.style || packData.system_prompt || null,
+    examples: packData.examples || null,
+    fallback_phrases: packData.fallback_phrases || null,
+    overlay_colors: packData.overlay_colors || null,
+  };
+}
+
+/**
+ * List all available voice packs.
+ * Returns [{ id, name }].
+ */
+export function listPacks() {
+  const packs = [];
+  let entries;
+  try {
+    entries = readdirSync(PACKS_DIR, { withFileTypes: true });
+  } catch {
+    return packs;
+  }
+
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const packJsonPath = join(PACKS_DIR, entry.name, "pack.json");
+    try {
+      const data = JSON.parse(readFileSync(packJsonPath, "utf-8"));
+      packs.push({ id: entry.name, name: data.name || entry.name });
+    } catch {
+      // skip invalid packs
+    }
+  }
+  return packs;
+}

package/src/paths.js

@@ -0,0 +1,39 @@
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+import { homedir } from "os";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+export const SCRIPT_DIR = dirname(__dirname);
+
+// Detect npm global install (src/ lives inside node_modules)
+export const IS_NPM_GLOBAL = SCRIPT_DIR.includes("node_modules");
+
+// User-level config and state in ~/.voxlert
+export const STATE_DIR = join(homedir(), ".voxlert");
+
+// When npm global: mutable data goes to ~/.voxlert/
+// When git clone: unchanged behavior (install dir)
+export const CONFIG_PATH = IS_NPM_GLOBAL
+  ? join(STATE_DIR, "config.json")
+  : join(SCRIPT_DIR, "config.json");
+export const PACKS_DIR = IS_NPM_GLOBAL
+  ? join(STATE_DIR, "packs")
+  : join(SCRIPT_DIR, "packs");
+export const CACHE_DIR = IS_NPM_GLOBAL
+  ? join(STATE_DIR, "cache")
+  : join(SCRIPT_DIR, "cache");
+export const COLLECT_DIR = IS_NPM_GLOBAL
+  ? join(STATE_DIR, "llm_collect")
+  : join(SCRIPT_DIR, "llm_collect");
+
+// Packs shipped with the npm package (read-only)
+export const BUNDLED_PACKS_DIR = join(SCRIPT_DIR, "packs");
+
+export const GLOBAL_USER_CONFIG_PATH = join(STATE_DIR, "config.json");
+export const QUEUE_DIR = join(STATE_DIR, "queue");
+export const LOCK_FILE = join(STATE_DIR, "playback.lock");
+export const LOG_FILE = join(STATE_DIR, "fallback.log");
+export const MAIN_LOG_FILE = join(STATE_DIR, "voxlert.log");
+export const HOOK_DEBUG_LOG = join(STATE_DIR, "hook-debug.log");
+export const USAGE_FILE = join(STATE_DIR, "usage.jsonl");
+export const PACK_VOLUME_CACHE_DIR = join(STATE_DIR, "pack-volume");

package/src/postinstall.js

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+
+// npm postinstall — prints setup instructions only, no file mutations.
+console.log(`
+╔══════════════════════════════════════════════╗
+║          Voxlert installed!               ║
+║                                              ║
+║  Run the setup wizard:                       ║
+║                                              ║
+║    voxlert setup                          ║
+║                                              ║
+╚══════════════════════════════════════════════╝
+`);

package/src/providers.js

@@ -0,0 +1,129 @@
+// LLM provider registry — base URLs, auth patterns, default models, signup URLs.
+// Anthropic uses its own Messages API format; all others are OpenAI-compatible.
+
+export const LLM_PROVIDERS = {
+  openrouter: {
+    name: "OpenRouter",
+    description: "200+ models, cheap",
+    baseUrl: "https://openrouter.ai/api/v1",
+    defaultModel: "google/gemma-3-27b-it",
+    signupUrl: "https://openrouter.ai/keys",
+    authHeader: (key) => ({ Authorization: `Bearer ${key}` }),
+    format: "openai",
+  },
+  openai: {
+    name: "OpenAI",
+    description: "GPT-4o-mini",
+    baseUrl: "https://api.openai.com/v1",
+    defaultModel: "gpt-4o-mini",
+    signupUrl: "https://platform.openai.com/api-keys",
+    authHeader: (key) => ({ Authorization: `Bearer ${key}` }),
+    format: "openai",
+  },
+  gemini: {
+    name: "Google Gemini",
+    description: "free tier available",
+    baseUrl: "https://generativelanguage.googleapis.com/v1beta/openai",
+    defaultModel: "gemini-2.0-flash",
+    signupUrl: "https://aistudio.google.com/apikey",
+    authHeader: (key) => ({ Authorization: `Bearer ${key}` }),
+    format: "openai",
+  },
+  anthropic: {
+    name: "Anthropic",
+    description: "Claude 3.5 Haiku",
+    baseUrl: "https://api.anthropic.com",
+    defaultModel: "claude-3-5-haiku-latest",
+    signupUrl: "https://console.anthropic.com/settings/keys",
+    authHeader: (key) => ({
+      "x-api-key": key,
+      "anthropic-version": "2023-06-01",
+    }),
+    format: "anthropic",
+  },
+};
+
+export function getProvider(id) {
+  return LLM_PROVIDERS[id] || null;
+}
+
+/**
+ * Resolve the API key for a given provider from config.
+ * Checks unified llm_api_key first, then legacy openrouter_api_key for backward compat.
+ */
+export function getApiKey(config) {
+  if (config.llm_api_key) return config.llm_api_key;
+  // Backward compat: openrouter_api_key
+  if (config.openrouter_api_key) return config.openrouter_api_key;
+  return "";
+}
+
+/**
+ * Resolve the model for a given provider from config.
+ */
+export function getModel(config) {
+  const provider = getProvider(config.llm_backend);
+  if (config.llm_model) return config.llm_model;
+  // Backward compat: openrouter_model
+  if (config.llm_backend === "openrouter" && config.openrouter_model) {
+    return config.openrouter_model;
+  }
+  return provider ? provider.defaultModel : "gpt-4o-mini";
+}
+
+/**
+ * Build the request body for the given provider format.
+ */
+export function formatRequestBody(provider, model, messages, maxTokens, temperature) {
+  if (provider.format === "anthropic") {
+    // Convert OpenAI-style messages to Anthropic Messages API format
+    const system = messages.find((m) => m.role === "system")?.content || "";
+    const userMessages = messages
+      .filter((m) => m.role !== "system")
+      .map((m) => ({ role: m.role, content: m.content }));
+    return JSON.stringify({
+      model,
+      max_tokens: maxTokens,
+      temperature,
+      system,
+      messages: userMessages,
+    });
+  }
+  // OpenAI-compatible format (openrouter, openai, gemini)
+  return JSON.stringify({
+    model,
+    messages,
+    max_tokens: maxTokens,
+    temperature,
+  });
+}
+
+/**
+ * Parse the response body from a provider into { phrase, usage }.
+ */
+export function parseResponse(provider, data) {
+  if (provider.format === "anthropic") {
+    const text = data.content?.[0]?.text || "";
+    const usage = data.usage
+      ? {
+          prompt_tokens: data.usage.input_tokens || 0,
+          completion_tokens: data.usage.output_tokens || 0,
+          total_tokens: (data.usage.input_tokens || 0) + (data.usage.output_tokens || 0),
+        }
+      : null;
+    return { text, usage };
+  }
+  // OpenAI-compatible
+  const text = data.choices?.[0]?.message?.content || "";
+  const usage = data.usage || null;
+  return { text, usage };
+}
+
+/**
+ * Get the full chat completions endpoint URL for a provider.
+ */
+export function getEndpointUrl(provider) {
+  const base = provider.baseUrl.replace(/\/+$/, "");
+  if (provider.format === "anthropic") return `${base}/v1/messages`;
+  return `${base}/chat/completions`;
+}