@settinghead/voxlert 0.3.5

package/src/hooks.js

@@ -0,0 +1,129 @@
+import { existsSync, readFileSync, writeFileSync, mkdirSync, rmSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+
+const SETTINGS_FILE = join(homedir(), ".claude", "settings.json");
+const SKILL_SRC = join(import.meta.dirname, "..", "skills", "voxlert-config", "SKILL.md");
+const SKILL_DEST_DIR = join(homedir(), ".claude", "skills", "voxlert-config");
+
+const HOOK_EVENTS = {
+  Stop: { matcher: "", timeout: 10, async: true },
+  Notification: { matcher: "", timeout: 10, async: true },
+  SessionEnd: { matcher: "", timeout: 10, async: true },
+  UserPromptSubmit: { matcher: "", timeout: 10, async: true },
+  PermissionRequest: { matcher: "", timeout: 10, async: true },
+  PreCompact: { matcher: "", timeout: 10, async: true },
+};
+
+function loadSettings() {
+  try {
+    return JSON.parse(readFileSync(SETTINGS_FILE, "utf-8"));
+  } catch {
+    return {};
+  }
+}
+
+function saveSettings(settings) {
+  mkdirSync(join(homedir(), ".claude"), { recursive: true });
+  writeFileSync(SETTINGS_FILE, JSON.stringify(settings, null, 2) + "\n");
+}
+
+export function hasVoxlertHooks() {
+  const settings = loadSettings();
+  if (!settings.hooks || typeof settings.hooks !== "object") return false;
+  return Object.values(settings.hooks).some(
+    (blocks) =>
+      Array.isArray(blocks) &&
+      blocks.some(
+        (block) =>
+          block.hooks &&
+          block.hooks.some((hook) => (hook.command || "").includes("voxlert")),
+      ),
+  );
+}
+
+/**
+ * Register Voxlert hooks in ~/.claude/settings.json.
+ * Idempotent — removes any existing voxlert hooks first, then adds fresh ones.
+ * @param {string} command — the hook command to execute (e.g. path to voxlert.sh or "voxlert hook")
+ */
+export function registerHooks(command) {
+  const settings = loadSettings();
+  if (!settings.hooks) settings.hooks = {};
+
+  for (const [event, cfg] of Object.entries(HOOK_EVENTS)) {
+    const hookEntry = {
+      type: "command",
+      command,
+      timeout: cfg.timeout,
+    };
+    if (cfg.async) hookEntry.async = true;
+
+    const matcherBlock = {
+      matcher: cfg.matcher,
+      hooks: [hookEntry],
+    };
+
+    if (!settings.hooks[event]) settings.hooks[event] = [];
+
+    // Remove any existing voxlert hooks for this event
+    settings.hooks[event] = settings.hooks[event].filter(
+      (block) =>
+        !block.hooks ||
+        !block.hooks.some((h) => (h.command || "").includes("voxlert")),
+    );
+
+    settings.hooks[event].push(matcherBlock);
+  }
+
+  saveSettings(settings);
+  return Object.keys(HOOK_EVENTS).length;
+}
+
+/**
+ * Remove all Voxlert hooks from ~/.claude/settings.json.
+ */
+export function unregisterHooks() {
+  const settings = loadSettings();
+  if (!settings.hooks) return 0;
+
+  let removed = 0;
+  for (const event of Object.keys(settings.hooks)) {
+    const before = settings.hooks[event].length;
+    settings.hooks[event] = settings.hooks[event].filter(
+      (block) =>
+        !block.hooks ||
+        !block.hooks.some((h) => (h.command || "").includes("voxlert")),
+    );
+    removed += before - settings.hooks[event].length;
+    if (settings.hooks[event].length === 0) delete settings.hooks[event];
+  }
+
+  if (Object.keys(settings.hooks).length === 0) delete settings.hooks;
+  saveSettings(settings);
+  return removed;
+}
+
+/**
+ * Install the voxlert-config skill to ~/.claude/skills/.
+ */
+export function installSkill() {
+  if (!existsSync(SKILL_SRC)) return false;
+  mkdirSync(SKILL_DEST_DIR, { recursive: true });
+  const content = readFileSync(SKILL_SRC, "utf-8");
+  writeFileSync(join(SKILL_DEST_DIR, "SKILL.md"), content);
+  return true;
+}
+
+export function hasInstalledSkill() {
+  return existsSync(join(SKILL_DEST_DIR, "SKILL.md"));
+}
+
+/**
+ * Remove the voxlert-config skill from ~/.claude/skills/.
+ */
+export function removeSkill() {
+  if (!existsSync(SKILL_DEST_DIR)) return false;
+  rmSync(SKILL_DEST_DIR, { recursive: true });
+  return true;
+}

package/src/llm.js

@@ -0,0 +1,237 @@
+import { readFileSync, writeFileSync, appendFileSync, mkdirSync } from "fs";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+import { request as httpsRequest } from "https";
+import { request as httpRequest } from "http";
+import { COLLECT_DIR, STATE_DIR, USAGE_FILE } from "./paths.js";
+import { buildSystemPrompt } from "./formats.js";
+import { getProvider, getApiKey, getModel, formatRequestBody, parseResponse, getEndpointUrl } from "./providers.js";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(readFileSync(join(__dirname, "..", "package.json"), "utf-8"));
+
+function saveLlmPair(messages, responseText, model, config) {
+  if (!config.collect_llm_data) return;
+  try {
+    mkdirSync(COLLECT_DIR, { recursive: true });
+    const record = {
+      timestamp: Date.now() / 1000,
+      version: pkg.version,
+      model,
+      messages,
+      response: responseText,
+    };
+    const filename = `${Date.now()}.json`;
+    writeFileSync(
+      join(COLLECT_DIR, filename),
+      JSON.stringify(record, null, 2),
+    );
+  } catch {
+    // ignore
+  }
+}
+
+function logUsage(model, usage) {
+  if (!usage) return;
+  try {
+    mkdirSync(STATE_DIR, { recursive: true });
+    const record = JSON.stringify({
+      timestamp: new Date().toISOString(),
+      model,
+      prompt_tokens: usage.prompt_tokens || 0,
+      completion_tokens: usage.completion_tokens || 0,
+      total_tokens: usage.total_tokens || 0,
+      cost: usage.cost != null ? usage.cost : undefined,
+    });
+    appendFileSync(USAGE_FILE, record + "\n");
+  } catch {
+    // best-effort
+  }
+}
+
+export function extractContext(eventData) {
+  const event = eventData.hook_event_name || "";
+
+  if (event === "Stop") {
+    const msg = eventData.last_assistant_message || "";
+    if (msg) {
+      return `${msg.slice(0, 300)}`;
+    }
+    const inputMessages = Array.isArray(eventData.input_messages) ? eventData.input_messages : [];
+    if (inputMessages.length > 0) {
+      return inputMessages.join(" ").slice(0, 300);
+    }
+    return null;
+  }
+
+  if (event === "PostToolUseFailure") {
+    const err = eventData.error_message || "";
+    if (err) {
+      return `Tool failed: ${err.slice(0, 280)}`;
+    }
+    return null;
+  }
+
+  return null;
+}
+
+function cleanPhrase(raw) {
+  let phrase = raw.trim().replace(/^["'.,!;:]+|["'.,!;:]+$/g, "").trim();
+  const words = phrase.split(/\s+/).slice(0, 8);
+  return words.length ? words.join(" ") : null;
+}
+
+/**
+ * Generic cloud LLM request — works with any provider in providers.js.
+ */
+function generatePhraseCloud(context, config, style, llmTemperature, examples) {
+  return new Promise((resolve) => {
+    const backendId = config.llm_backend || "openrouter";
+    const provider = getProvider(backendId);
+    if (!provider) return resolve({ phrase: null, fallbackReason: "unknown_provider", detail: backendId });
+
+    const apiKey = getApiKey(config);
+    if (!apiKey) return resolve({ phrase: null, fallbackReason: "no_api_key" });
+
+    const model = getModel(config);
+    const messages = [
+      { role: "system", content: buildSystemPrompt(style, "status-report", examples) },
+      { role: "user", content: context },
+    ];
+    const temperature = llmTemperature != null ? llmTemperature : 0.9;
+    const payload = formatRequestBody(provider, model, messages, 30, temperature);
+
+    let url;
+    try {
+      url = new URL(getEndpointUrl(provider));
+    } catch {
+      return resolve({ phrase: null, fallbackReason: "invalid_base_url", detail: provider.baseUrl });
+    }
+
+    const authHeaders = provider.authHeader(apiKey);
+    const headers = {
+      ...authHeaders,
+      "Content-Type": "application/json",
+      "Content-Length": Buffer.byteLength(payload),
+    };
+
+    const isHttps = url.protocol === "https:";
+    const reqFn = isHttps ? httpsRequest : httpRequest;
+
+    const req = reqFn(
+      url,
+      { method: "POST", headers, timeout: 5000 },
+      (res) => {
+        let data = "";
+        res.on("data", (chunk) => (data += chunk));
+        res.on("end", () => {
+          try {
+            const result = JSON.parse(data);
+            const parsed = parseResponse(provider, result);
+            logUsage(model, parsed.usage);
+            const phrase = cleanPhrase(parsed.text);
+            saveLlmPair(messages, parsed.text, model, config);
+            if (phrase) {
+              resolve({ phrase, fallbackReason: null, usage: parsed.usage });
+            } else {
+              resolve({ phrase: null, fallbackReason: "empty_response", detail: result, usage: parsed.usage });
+            }
+          } catch (err) {
+            resolve({ phrase: null, fallbackReason: "parse_error", detail: `${err.message}; body=${data.slice(0, 200)}` });
+          }
+        });
+      },
+    );
+
+    req.on("error", (err) => resolve({ phrase: null, fallbackReason: "request_error", detail: err.message }));
+    req.on("timeout", () => {
+      req.destroy();
+      resolve({ phrase: null, fallbackReason: "timeout" });
+    });
+    req.write(payload);
+    req.end();
+  });
+}
+
+function generatePhraseLocal(context, config, style, llmTemperature, examples) {
+  return new Promise((resolve) => {
+    const local = config.local_api || {};
+    const baseUrl = local.base_url || "http://localhost:8000";
+    const model = local.model || "default";
+    const maxTokens = local.max_tokens || 50;
+    const timeout = local.timeout || 15000;
+
+    const messages = [
+      { role: "system", content: buildSystemPrompt(style, "status-report", examples) },
+      { role: "user", content: context },
+    ];
+
+    const payload = JSON.stringify({
+      model,
+      messages,
+      max_tokens: maxTokens,
+      temperature: llmTemperature != null ? llmTemperature : 0.9,
+    });
+
+    let url;
+    try {
+      url = new URL("/v1/chat/completions", baseUrl);
+    } catch {
+      return resolve({ phrase: null, fallbackReason: "invalid_base_url", detail: baseUrl });
+    }
+
+    const isHttps = url.protocol === "https:";
+    const reqFn = isHttps ? httpsRequest : httpRequest;
+
+    const req = reqFn(
+      url,
+      {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "Content-Length": Buffer.byteLength(payload),
+        },
+        timeout,
+      },
+      (res) => {
+        let data = "";
+        res.on("data", (chunk) => (data += chunk));
+        res.on("end", () => {
+          try {
+            const result = JSON.parse(data);
+            const usage = result.usage || null;
+            logUsage(model, usage);
+            const phrase = cleanPhrase(result.choices[0].message.content);
+            saveLlmPair(messages, result.choices[0].message.content, model, config);
+            if (phrase) {
+              resolve({ phrase, fallbackReason: null, usage });
+            } else {
+              resolve({ phrase: null, fallbackReason: "empty_response", detail: result, usage });
+            }
+          } catch (err) {
+            resolve({ phrase: null, fallbackReason: "parse_error", detail: `${err.message}; body=${data.slice(0, 200)}` });
+          }
+        });
+      },
+    );
+
+    req.on("error", (err) => resolve({ phrase: null, fallbackReason: "request_error", detail: err.message }));
+    req.on("timeout", () => {
+      req.destroy();
+      resolve({ phrase: null, fallbackReason: "timeout" });
+    });
+    req.write(payload);
+    req.end();
+  });
+}
+
+// Backward-compatible export
+export { generatePhraseCloud as generatePhraseLlm };
+
+export function generatePhrase(context, config, style, llmTemperature, examples) {
+  const backend = config.llm_backend || "openrouter";
+  if (backend === "local") {
+    return generatePhraseLocal(context, config, style, llmTemperature, examples);
+  }
+  return generatePhraseCloud(context, config, style, llmTemperature, examples);
+}

package/src/overlay.js

@@ -0,0 +1,212 @@
+/**
+ * Voxlert — On-screen notification wrapper.
+ *
+ * - macOS: Custom Cocoa overlay via JXA (overlay.jxa) — gradient, icon, stacking.
+ * - Windows/Linux: System notifications via node-notifier (native toasts / notify-send).
+ * No-op when overlay is disabled in config.
+ */
+
+import { join, dirname } from "path";
+import { existsSync, mkdirSync, rmdirSync, readdirSync, statSync } from "fs";
+import { spawn } from "child_process";
+import { fileURLToPath } from "url";
+import { createRequire } from "module";
+
+const require = createRequire(import.meta.url);
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const SCRIPT_DIR = dirname(__dirname);
+const JXA_SCRIPT = join(__dirname, "overlay.jxa");
+const SLOT_DIR = "/tmp/voxlert-popups";
+const MAX_SLOTS = 5;
+const STALE_MS = 60_000;
+
+const OVERLAY_DEBUG = process.env.VOXLERT_OVERLAY_DEBUG === "1" || process.env.VOXLERT_OVERLAY_DEBUG === "true";
+function overlayDebug(msg, ...args) {
+  if (OVERLAY_DEBUG) console.error("[voxlert overlay]", msg, ...args);
+}
+
+// Default gradient (dark charcoal)
+const DEFAULT_COLORS = [[0.15, 0.15, 0.2], [0.1, 0.1, 0.15]];
+
+/**
+ * Acquire a slot for vertical stacking. Uses mkdir for race-safe locking.
+ * Returns slot index (0-based) or -1 if all slots taken.
+ */
+function acquireSlot() {
+  mkdirSync(SLOT_DIR, { recursive: true });
+
+  // Clean stale slots first
+  try {
+    const entries = readdirSync(SLOT_DIR);
+    const now = Date.now();
+    for (const entry of entries) {
+      if (!entry.startsWith("slot-")) continue;
+      try {
+        const st = statSync(join(SLOT_DIR, entry));
+        if (now - st.mtimeMs > STALE_MS) {
+          rmdirSync(join(SLOT_DIR, entry));
+        }
+      } catch {
+        // already removed
+      }
+    }
+  } catch {
+    // best-effort cleanup
+  }
+
+  // Try to acquire a slot
+  for (let i = 0; i < MAX_SLOTS; i++) {
+    const slotPath = join(SLOT_DIR, `slot-${i}`);
+    try {
+      mkdirSync(slotPath);
+      return i;
+    } catch {
+      // slot taken, try next
+    }
+  }
+  return -1;
+}
+
+/**
+ * Release a slot after dismiss + buffer time.
+ */
+function releaseSlotAfter(slot, delaySecs) {
+  const slotPath = join(SLOT_DIR, `slot-${slot}`);
+  setTimeout(() => {
+    try {
+      rmdirSync(slotPath);
+    } catch {
+      // already removed
+    }
+  }, delaySecs * 1000);
+}
+
+/**
+ * Resolve icon path for a pack. Looks for assets/{packId}.{png,jpg,gif}.
+ */
+function resolveIcon(packId) {
+  if (!packId) return "";
+  const exts = ["png", "jpg", "gif"];
+  for (const ext of exts) {
+    const p = join(SCRIPT_DIR, "assets", `${packId}.${ext}`);
+    if (existsSync(p)) return p;
+  }
+  return "";
+}
+
+/**
+ * Show an overlay notification.
+ * Never throws — any failure is caught and logged; the rest of the pipeline (e.g. audio) continues.
+ * Fire-and-forget: spawns osascript (macOS) or uses node-notifier and returns immediately.
+ *
+ * @param {string} phrase - The phrase to display
+ * @param {object} opts
+ * @param {string} opts.category - Event category
+ * @param {string} opts.packName - Display name of the voice pack
+ * @param {string} opts.packId - Pack identifier (for icon lookup)
+ * @param {string} opts.prefix - Resolved prefix string
+ * @param {object} opts.config - Loaded config object
+ * @param {Array} [opts.overlayColors] - Gradient colors from pack
+ */
+export function showOverlay(phrase, { category, packName, packId, prefix, config, overlayColors } = {}) {
+  overlayDebug("showOverlay called", { phrase: phrase?.slice(0, 40), platform: process.platform, configOverlay: config?.overlay });
+
+  if (config && config.overlay === false) {
+    overlayDebug("skip: overlay disabled in config");
+    return;
+  }
+
+  try {
+    runOverlay(phrase, { category, packName, packId, prefix, config, overlayColors });
+  } catch (err) {
+    overlayDebug("notification failed (non-fatal)", err?.message || err);
+  }
+}
+
+function runOverlay(phrase, { packName, packId, prefix, config, overlayColors } = {}) {
+  const platform = process.platform;
+  const style = config?.overlay_style || "custom";
+
+  // Use system notification (node-notifier) when style is "system" or on non-darwin (no custom option there)
+  const useSystem = style === "system" || platform === "win32" || platform === "linux";
+
+  // Build subtitle and display phrase (shared)
+  let subtitle = "";
+  const parts = [];
+  if (prefix) parts.push(prefix);
+  if (packName) parts.push(String(packName).toUpperCase());
+  subtitle = parts.join("  ·  ");
+  let displayPhrase = phrase;
+  if (prefix && phrase.startsWith(prefix + "; ")) {
+    displayPhrase = phrase.slice(prefix.length + 2);
+  }
+  const iconPath = resolveIcon(packId);
+
+  // --- System notification (node-notifier): Windows, Linux, or macOS when overlay_style === "system" ---
+  if (useSystem) {
+    try {
+      const notifier = require("node-notifier");
+      notifier.notify({
+        title: subtitle || "Voxlert",
+        message: displayPhrase || phrase,
+        icon: iconPath || undefined,
+        sound: false,
+      });
+      overlayDebug("node-notifier sent");
+    } catch (err) {
+      overlayDebug("node-notifier failed", err?.message || err);
+    }
+    return;
+  }
+
+  // --- macOS only: custom JXA overlay (when overlay_style === "custom") ---
+  if (platform !== "darwin") {
+    overlayDebug("skip: unsupported platform");
+    return;
+  }
+
+  if (!existsSync(JXA_SCRIPT)) {
+    overlayDebug("skip: JXA script not found", JXA_SCRIPT);
+    return;
+  }
+  overlayDebug("JXA script exists", JXA_SCRIPT);
+
+  const dismissSecs = (config && config.overlay_dismiss) || 4;
+  const colors = overlayColors || DEFAULT_COLORS;
+
+  // Acquire stacking slot
+  const slot = acquireSlot();
+  if (slot < 0) {
+    overlayDebug("skip: no free slot (all slots taken)");
+    return;
+  }
+  overlayDebug("acquired slot", slot);
+
+  // Spawn osascript detached
+  const args = [
+    "-l", "JavaScript",
+    JXA_SCRIPT,
+    displayPhrase,
+    JSON.stringify(colors),
+    iconPath,
+    String(slot),
+    String(dismissSecs),
+    subtitle,
+  ];
+  overlayDebug("spawning osascript", args.slice(0, 4), "...");
+
+  try {
+    const child = spawn("osascript", args, {
+      stdio: "ignore",
+      detached: true,
+    });
+    child.unref();
+    overlayDebug("osascript spawned pid", child.pid);
+  } catch (err) {
+    overlayDebug("osascript spawn failed", err?.message || err);
+    // best-effort — don't break audio pipeline
+  }
+
+  // Schedule slot release after dismiss + 2s buffer
+  releaseSlotAfter(slot, dismissSecs + 2);
+}