@settinghead/voxlert 0.3.5

package/src/commands/config.js

@@ -0,0 +1,141 @@
+import { existsSync, readFileSync, writeFileSync } from "fs";
+import { join } from "path";
+import { loadConfig, saveConfig } from "../config.js";
+import { CONFIG_PATH } from "../paths.js";
+
+function maskKey(key) {
+  if (!key || typeof key !== "string") return "(not set)";
+  if (key.length <= 8) return "****";
+  return key.slice(0, 4) + "…" + key.slice(-4);
+}
+
+function coerceValue(value) {
+  if (value === "null") return null;
+  if (value === "true") return true;
+  if (value === "false") return false;
+  if (value !== "" && !isNaN(Number(value))) return Number(value);
+  return value;
+}
+
+function setValue(target, key, value) {
+  const dotIdx = key.indexOf(".");
+  if (dotIdx !== -1) {
+    const parent = key.slice(0, dotIdx);
+    const child = key.slice(dotIdx + 1);
+    if (!target[parent] || typeof target[parent] !== "object") {
+      target[parent] = {};
+    }
+    target[parent][child] = value;
+    return;
+  }
+  target[key] = value;
+}
+
+function showConfig() {
+  const config = loadConfig(process.cwd());
+  const display = { ...config };
+  if (display.llm_api_key) display.llm_api_key = maskKey(display.llm_api_key);
+  if (display.openrouter_api_key) display.openrouter_api_key = maskKey(display.openrouter_api_key);
+  console.log(JSON.stringify(display, null, 2));
+}
+
+function configSet(key, value) {
+  if (!key) {
+    console.error("Usage: voxlert config set <key> <value>");
+    process.exit(1);
+  }
+  const config = loadConfig(process.cwd());
+  setValue(config, key, coerceValue(value));
+  saveConfig(config);
+  console.log(`Set ${key} = ${JSON.stringify(coerceValue(value))}`);
+}
+
+function configSetLocal(key, value) {
+  if (!key) {
+    console.error("Usage: voxlert config local set <key> <value>");
+    process.exit(1);
+  }
+  const filePath = join(process.cwd(), ".voxlert.json");
+  let local = {};
+  try {
+    if (existsSync(filePath)) local = JSON.parse(readFileSync(filePath, "utf-8"));
+  } catch {
+    // malformed — overwrite
+  }
+  setValue(local, key, coerceValue(value));
+  writeFileSync(filePath, JSON.stringify(local, null, 2) + "\n");
+  console.log(`Set ${key} = ${JSON.stringify(coerceValue(value))} in ${filePath}`);
+}
+
+function configSetSource(name, key, value) {
+  if (!name || !key) {
+    console.error("Usage: voxlert config source <name> set <key> <value>");
+    process.exit(1);
+  }
+  const config = loadConfig(process.cwd());
+  if (!config.sources) config.sources = {};
+  if (!config.sources[name] || typeof config.sources[name] !== "object") config.sources[name] = {};
+  setValue(config.sources[name], key, coerceValue(value));
+  saveConfig(config);
+  console.log(`Set sources.${name}.${key} = ${JSON.stringify(coerceValue(value))}`);
+}
+
+export const configCommand = {
+  name: "config",
+  aliases: [],
+  help: [
+    "  voxlert config                    Show current configuration",
+    "  voxlert config show               Show current configuration",
+    "  voxlert config set <k> <v>        Set a global config value (supports categories.X dot notation)",
+    "  voxlert config path               Print global config file path",
+    "  voxlert config local              Show local (project) config for current directory",
+    "  voxlert config local set <k> <v>  Set a value in .voxlert.json in the current directory",
+    "  voxlert config local path         Print path to local config file",
+    "  voxlert config source <name>              Show overrides for a source (cursor, claude, codex)",
+    "  voxlert config source <name> set <k> <v> Set a per-source override (supports categories.X dot notation)",
+  ],
+  skipSetupWizard: true,
+  skipUpgradeCheck: false,
+  async run(context) {
+    const [, sub, ...rest] = context.args;
+    if (sub === "set") {
+      configSet(rest[0], rest.slice(1).join(" "));
+      return;
+    }
+    if (sub === "local") {
+      if (rest[0] === "set") {
+        configSetLocal(rest[1], rest.slice(2).join(" "));
+      } else if (rest[0] === "path") {
+        console.log(join(process.cwd(), ".voxlert.json"));
+      } else {
+        const localPath = join(process.cwd(), ".voxlert.json");
+        if (existsSync(localPath)) {
+          console.log(readFileSync(localPath, "utf-8"));
+        } else {
+          console.log("No local config found in", process.cwd());
+        }
+      }
+      return;
+    }
+    if (sub === "source") {
+      const srcName = rest[0];
+      if (rest[1] === "set") {
+        configSetSource(srcName, rest[2], rest.slice(3).join(" "));
+      } else {
+        const cfg = loadConfig(process.cwd());
+        const srcCfg = (cfg.sources || {})[srcName];
+        if (srcCfg) {
+          console.log(JSON.stringify(srcCfg, null, 2));
+        } else {
+          console.log(`No source overrides configured for "${srcName}"`);
+        }
+      }
+      return;
+    }
+    if (sub === "path") {
+      console.log(CONFIG_PATH);
+      return;
+    }
+    showConfig();
+  },
+};

package/src/commands/cost.js

@@ -0,0 +1,20 @@
+import { formatCost, resetUsage } from "../cost.js";
+
+export const costCommand = {
+  name: "cost",
+  aliases: [],
+  help: [
+    "  voxlert cost                Show accumulated token usage and estimated cost",
+    "  voxlert cost reset          Clear the usage log",
+  ],
+  skipSetupWizard: false,
+  skipUpgradeCheck: false,
+  async run(context) {
+    if (context.args[1] === "reset") {
+      resetUsage();
+      console.log("Usage log cleared.");
+      return;
+    }
+    console.log(await formatCost());
+  },
+};

package/src/commands/cursor-hook.js

@@ -0,0 +1,52 @@
+import { processHookEvent } from "../voxlert.js";
+import { CURSOR_TO_VOXLERT_EVENT, getLastAssistantFromTranscript } from "./hook-utils.js";
+
+export const cursorHookCommand = {
+  name: "cursor-hook",
+  aliases: [],
+  help: [
+    "  voxlert cursor-hook         Process a hook event from stdin (used by Cursor hooks)",
+  ],
+  skipSetupWizard: true,
+  skipUpgradeCheck: true,
+  async run() {
+    let input = "";
+    for await (const chunk of process.stdin) {
+      input += chunk;
+    }
+    let payload;
+    try {
+      payload = JSON.parse(input);
+    } catch {
+      process.stdout.write("{}\n");
+      return;
+    }
+    const cursorEvent = payload.hook_event_name || "";
+    const ourEvent = CURSOR_TO_VOXLERT_EVENT[cursorEvent];
+    if (!ourEvent) {
+      process.stdout.write("{}\n");
+      return;
+    }
+    const workspaceRoots = payload.workspace_roots;
+    const cwd = Array.isArray(workspaceRoots) && workspaceRoots[0] ? workspaceRoots[0] : "";
+    const translated = {
+      ...payload,
+      hook_event_name: ourEvent,
+      cwd,
+      source: "cursor",
+    };
+    if (ourEvent === "Stop" && payload.transcript_path) {
+      const last = getLastAssistantFromTranscript(payload.transcript_path);
+      if (last) translated.last_assistant_message = last;
+    }
+    if (ourEvent === "PostToolUseFailure" && payload.error_message) {
+      translated.error_message = payload.error_message;
+    }
+    try {
+      await processHookEvent(translated);
+    } catch {
+      // best-effort: still return {} so Cursor doesn't error
+    }
+    process.stdout.write("{}\n");
+  },
+};

package/src/commands/help.js

@@ -0,0 +1,25 @@
+export function formatHelp(commands, pkg) {
+  const sections = commands
+    .filter((command) => Array.isArray(command.help) && command.help.length > 0)
+    .map((command) => command.help.join("\n"));
+
+  return [
+    `voxlert v${pkg.version} — Game character voice notifications for Claude Code, Cursor, Codex, and OpenClaw`,
+    "",
+    "Usage:",
+    ...sections,
+  ].join("\n");
+}
+
+export const helpCommand = {
+  name: "help",
+  aliases: ["--help", "-h"],
+  help: [
+    "  voxlert help                Show this help message",
+  ],
+  skipSetupWizard: true,
+  skipUpgradeCheck: false,
+  async run(context) {
+    console.log(context.formatHelp());
+  },
+};

package/src/commands/hook-utils.js

@@ -0,0 +1,73 @@
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from "fs";
+import { CONFIG_PATH, HOOK_DEBUG_LOG, IS_NPM_GLOBAL, SCRIPT_DIR, STATE_DIR } from "../paths.js";
+import { getCodexConfigPath } from "../codex-config.js";
+
+export const CURSOR_TO_VOXLERT_EVENT = {
+  sessionStart: "SessionStart",
+  sessionEnd: "SessionEnd",
+  stop: "Stop",
+  postToolUseFailure: "PostToolUseFailure",
+  preCompact: "PreCompact",
+};
+
+export const CODEX_NOTIFY_TYPE_TO_EVENT = {
+  "agent-turn-complete": "Stop",
+};
+
+export function appendHookDebugLine(message) {
+  try {
+    mkdirSync(STATE_DIR, { recursive: true });
+    appendFileSync(HOOK_DEBUG_LOG, `[${new Date().toISOString()}] ${message}\n`);
+  } catch {
+    // best-effort
+  }
+}
+
+export function stringifyForLog(value, limit = 1000) {
+  try {
+    const text = typeof value === "string" ? value : JSON.stringify(value);
+    if (typeof text !== "string") return String(value);
+    return text.length > limit ? `${text.slice(0, limit)}…` : text;
+  } catch {
+    return String(value);
+  }
+}
+
+export function listEnvKeys(prefixes) {
+  return Object.keys(process.env)
+    .filter((key) => prefixes.some((prefix) => key.startsWith(prefix)))
+    .sort();
+}
+
+export function normalizeCodexInputMessages(payload) {
+  const value = payload["input-messages"] || payload.input_messages || payload.inputMessages;
+  if (!Array.isArray(value)) return [];
+  return value.filter((item) => typeof item === "string" && item.trim());
+}
+
+export function getLastAssistantFromTranscript(transcriptPath) {
+  try {
+    if (!transcriptPath || !existsSync(transcriptPath)) return null;
+    const raw = readFileSync(transcriptPath, "utf-8");
+    if (!raw || !raw.trim()) return null;
+    const slice = raw.length > 500 ? raw.slice(-500) : raw;
+    return slice.trim();
+  } catch {
+    return null;
+  }
+}
+
+export function getHookRuntimeInfo() {
+  return {
+    pid: process.pid,
+    ppid: process.ppid,
+    execPath: process.execPath,
+    node: process.version,
+    cwd: process.cwd(),
+    scriptDir: SCRIPT_DIR,
+    isNpmGlobal: IS_NPM_GLOBAL,
+    configPath: CONFIG_PATH,
+    codexConfigPath: getCodexConfigPath(),
+    envKeys: listEnvKeys(["CODEX", "VOXLERT", "OPENAI"]),
+  };
+}

package/src/commands/hook.js

@@ -0,0 +1,27 @@
+import { processHookEvent } from "../voxlert.js";
+import { appendHookDebugLine, stringifyForLog } from "./hook-utils.js";
+
+export const hookCommand = {
+  name: "hook",
+  aliases: [],
+  help: [
+    "  voxlert hook                Process a hook event from stdin (used by Claude Code hooks)",
+  ],
+  skipSetupWizard: true,
+  skipUpgradeCheck: true,
+  async run() {
+    let input = "";
+    for await (const chunk of process.stdin) {
+      input += chunk;
+    }
+    try {
+      appendHookDebugLine(`voxlert hook stdin received length=${input.length} raw=${stringifyForLog(input, 200)}`);
+      const eventData = JSON.parse(input);
+      if (!eventData.source) eventData.source = "claude";
+      appendHookDebugLine(`voxlert hook parsed eventData ${stringifyForLog(eventData)}`);
+      await processHookEvent(eventData);
+    } catch (err) {
+      appendHookDebugLine(`voxlert hook parse/process error ${err && err.message}`);
+    }
+  },
+};

package/src/commands/index.js

@@ -0,0 +1,45 @@
+import { codexNotifyCommand } from "./codex-notify.js";
+import { configCommand } from "./config.js";
+import { costCommand } from "./cost.js";
+import { cursorHookCommand } from "./cursor-hook.js";
+import { helpCommand } from "./help.js";
+import { hookCommand } from "./hook.js";
+import { logCommand } from "./log.js";
+import { notificationCommand } from "./notification.js";
+import { packCommand } from "./pack.js";
+import { setupCommand } from "./setup.js";
+import { testCommand } from "./test.js";
+import { uninstallCommand } from "./uninstall.js";
+import { versionCommand } from "./version.js";
+import { voiceCommand } from "./voice.js";
+import { volumeCommand } from "./volume.js";
+
+export const COMMANDS = [
+  setupCommand,
+  hookCommand,
+  cursorHookCommand,
+  codexNotifyCommand,
+  configCommand,
+  logCommand,
+  voiceCommand,
+  packCommand,
+  volumeCommand,
+  notificationCommand,
+  testCommand,
+  costCommand,
+  uninstallCommand,
+  helpCommand,
+  versionCommand,
+];
+
+const COMMAND_LOOKUP = new Map();
+for (const command of COMMANDS) {
+  COMMAND_LOOKUP.set(command.name, command);
+  for (const alias of command.aliases || []) {
+    COMMAND_LOOKUP.set(alias, command);
+  }
+}
+
+export function resolveCommand(name) {
+  return COMMAND_LOOKUP.get(name) || null;
+}

package/src/commands/log.js

@@ -0,0 +1,92 @@
+import { existsSync, readFileSync, watchFile } from "fs";
+import { loadConfig, saveConfig } from "../config.js";
+import { LOG_FILE, MAIN_LOG_FILE } from "../paths.js";
+
+const TAIL_LINES = 100;
+
+function tailLog() {
+  if (!existsSync(MAIN_LOG_FILE)) {
+    console.log("(No activity log yet. Logging is on by default; events will appear here.)");
+    console.log("Path: " + MAIN_LOG_FILE);
+  }
+  let lastSize = 0;
+  function readNew() {
+    try {
+      const content = readFileSync(MAIN_LOG_FILE, "utf-8");
+      if (content.length < lastSize) lastSize = 0;
+      if (content.length > lastSize) {
+        const newPart = content.slice(lastSize);
+        process.stdout.write(newPart);
+        lastSize = content.length;
+      }
+    } catch {
+      // file may have been removed
+    }
+  }
+  function init() {
+    try {
+      const content = readFileSync(MAIN_LOG_FILE, "utf-8");
+      const lines = content.split("\n").filter((line) => line.length > 0);
+      const toShow = lines.slice(-TAIL_LINES);
+      toShow.forEach((line) => console.log(line));
+      lastSize = content.length;
+    } catch {
+      lastSize = 0;
+    }
+  }
+  init();
+  watchFile(MAIN_LOG_FILE, { interval: 500 }, () => {
+    readNew();
+  });
+  process.stdin.resume();
+}
+
+function setLoggingOnOff(value) {
+  const config = loadConfig(process.cwd());
+  config.logging = value === "on" || value === true;
+  saveConfig(config);
+  console.log("Activity logging: " + (config.logging ? "on" : "off"));
+}
+
+function setErrorLogOnOff(value) {
+  const config = loadConfig(process.cwd());
+  config.error_log = value === "on" || value === true;
+  saveConfig(config);
+  console.log("Error (fallback) logging: " + (config.error_log ? "on" : "off"));
+}
+
+export const logCommand = {
+  name: "log",
+  aliases: [],
+  help: [
+    "  voxlert log                  Stream activity log (tail -f style)",
+    "  voxlert log path             Print activity log file path",
+    "  voxlert log error-path       Print error/fallback log file path",
+    "  voxlert log on | off         Enable or disable activity logging",
+    "  voxlert log error on | off   Enable or disable error (fallback) logging",
+  ],
+  skipSetupWizard: true,
+  skipUpgradeCheck: false,
+  async run(context) {
+    const [, sub, arg] = context.args;
+    if (sub === "path") {
+      console.log(MAIN_LOG_FILE);
+    } else if (sub === "error-path") {
+      console.log(LOG_FILE);
+    } else if (sub === "on" || sub === "off") {
+      setLoggingOnOff(sub);
+    } else if (sub === "error" && (arg === "on" || arg === "off")) {
+      setErrorLogOnOff(arg);
+    } else if (!sub || sub === "tail") {
+      tailLog();
+    } else {
+      console.log("Activity log: " + MAIN_LOG_FILE);
+      console.log("Error log: " + LOG_FILE);
+      console.log("Use: voxlert log          (stream activity log)");
+      console.log("      voxlert log path    (activity log path)");
+      console.log("      voxlert log error-path");
+      console.log("      voxlert log on | off");
+      console.log("      voxlert log error on | off");
+    }
+  },
+};

package/src/commands/notification.js

@@ -0,0 +1,50 @@
+import select from "@inquirer/select";
+import { loadConfig, saveConfig } from "../config.js";
+
+async function notificationPick() {
+  const config = loadConfig(process.cwd());
+  const platform = process.platform;
+  const currentOverlay = config.overlay !== false;
+  const currentStyle = config.overlay_style || "custom";
+
+  const choices =
+    platform === "darwin"
+      ? [
+          { value: "custom", name: "Custom overlay (popup)", description: "In-app style popup with gradient and icon" },
+          { value: "system", name: "System notification", description: "macOS Notification Center" },
+          { value: "off", name: "Off", description: "No popup, voice only" },
+        ]
+      : [
+          { value: "system", name: "System notification", description: platform === "win32" ? "Windows toast" : "notify-send / system tray" },
+          { value: "off", name: "Off", description: "No popup, voice only" },
+        ];
+
+  const currentValue =
+    !currentOverlay ? "off" : platform === "darwin" ? currentStyle : currentOverlay ? "system" : "off";
+
+  const chosen = await select({
+    message: "Notification style",
+    choices,
+    default: currentValue,
+  });
+
+  config.overlay = chosen !== "off";
+  if (chosen !== "off") config.overlay_style = chosen;
+  saveConfig(config);
+
+  const labels = { custom: "Custom overlay", system: "System notification", off: "Off" };
+  console.log(`Notifications: ${labels[chosen]}`);
+}
+
+export const notificationCommand = {
+  name: "notification",
+  aliases: ["notify"],
+  help: [
+    "  voxlert notification        Choose notification style (popup / system / off)",
+  ],
+  skipSetupWizard: true,
+  skipUpgradeCheck: false,
+  async run() {
+    await notificationPick();
+  },
+};

package/src/commands/pack-helpers.js

@@ -0,0 +1,157 @@
+import { createInterface } from "readline";
+import select from "@inquirer/select";
+import { loadConfig, saveConfig } from "../config.js";
+import { showOverlay } from "../overlay.js";
+import { listPacks, loadPack } from "../packs.js";
+import { generatePhrase } from "../llm.js";
+import { speakPhrase } from "../audio.js";
+
+export async function testPipeline(text, pack) {
+  if (!text) {
+    console.error("Usage: voxlert test \"<text>\"");
+    process.exit(1);
+  }
+
+  const config = loadConfig(process.cwd());
+  const activePack = pack || loadPack(config);
+
+  console.log(`Input: ${text}`);
+  console.log(`Pack: ${activePack.name} (${activePack.id}), echo: ${activePack.echo !== false}`);
+  console.log("Generating phrase via LLM...");
+
+  const result = await generatePhrase(text, config, activePack.style, activePack.llm_temperature, activePack.examples);
+
+  let phrase;
+  if (result.phrase) {
+    phrase = result.phrase;
+    console.log(`LLM phrase: ${phrase}`);
+    if (result.usage) {
+      console.log(`Tokens: ${result.usage.total_tokens || 0} (${result.usage.prompt_tokens || 0} prompt + ${result.usage.completion_tokens || 0} completion)`);
+    }
+  } else {
+    console.log(`LLM failed (${result.fallbackReason}), using raw text as phrase.`);
+    phrase = text;
+  }
+
+  console.log("Sending to TTS...");
+  showOverlay(phrase, {
+    category: "notification",
+    packName: activePack.name,
+    packId: activePack.id || (config.active_pack || "sc2-adjutant"),
+    prefix: "Test",
+    config,
+    overlayColors: activePack.overlay_colors,
+  });
+  await speakPhrase(phrase, config, activePack);
+  console.log("Done.");
+}
+
+export function packList() {
+  const packs = listPacks();
+  const config = loadConfig(process.cwd());
+  const active = config.active_pack || "";
+  if (packs.length === 0) {
+    console.log("No voice packs found.");
+    return;
+  }
+  const randomMarker = active === "random" ? " (active)" : "";
+  console.log(`  random — Random (picks a different voice each time)${randomMarker}`);
+  for (const pack of packs) {
+    const marker = pack.id === active ? " (active)" : "";
+    console.log(`  ${pack.id} — ${pack.name}${marker}`);
+  }
+}
+
+export function packShow() {
+  const config = loadConfig(process.cwd());
+  console.log(JSON.stringify(loadPack(config), null, 2));
+}
+
+export async function greetWithVoice() {
+  const config = loadConfig(process.cwd());
+  const pack = loadPack(config);
+  await testPipeline(`You have chosen '${pack.name}' as the new voice. It is now activated.`, pack);
+}
+
+export async function packUse(packId) {
+  if (!packId) {
+    console.error("Usage: voxlert pack use <pack-id>");
+    process.exit(1);
+  }
+  if (packId === "random") {
+    const config = loadConfig(process.cwd());
+    config.active_pack = "random";
+    saveConfig(config);
+    console.log("Switched to pack: Random (picks a different voice each time)");
+    return;
+  }
+  const packs = listPacks();
+  const match = packs.find((pack) => pack.id === packId);
+  if (!match) {
+    console.error(`Pack "${packId}" not found. Available packs:`);
+    console.error("  random — Random (picks a different voice each time)");
+    for (const pack of packs) console.error(`  ${pack.id} — ${pack.name}`);
+    process.exit(1);
+  }
+  const config = loadConfig(process.cwd());
+  config.active_pack = packId;
+  saveConfig(config);
+  console.log(`Switched to pack: ${match.name} (${packId})`);
+  await greetWithVoice();
+}
+
+export async function voicePick() {
+  const packs = listPacks();
+  if (packs.length === 0) {
+    console.log("No voice packs found.");
+    return;
+  }
+
+  const config = loadConfig(process.cwd());
+  const active = config.active_pack || "";
+  const choices = [
+    {
+      name: active === "random" ? "Random (active)" : "Random",
+      value: "random",
+      description: "Picks a different voice each time",
+    },
+    ...packs.map((pack) => ({
+      name: pack.id === active ? `${pack.name} (active)` : pack.name,
+      value: pack.id,
+      description: pack.id,
+    })),
+  ];
+
+  const chosen = await select({
+    message: "Select a voice pack",
+    choices,
+    default: active || undefined,
+  });
+
+  if (chosen === active) {
+    const selectedPack = packs.find((pack) => pack.id === chosen);
+    const label = chosen === "random" ? "Random" : selectedPack.name;
+    console.log(`Already using: ${label}`);
+    return;
+  }
+
+  config.active_pack = chosen;
+  saveConfig(config);
+  if (chosen === "random") {
+    console.log("Switched to: Random");
+  } else {
+    const match = packs.find((pack) => pack.id === chosen);
+    console.log(`Switched to: ${match.name} (${chosen})`);
+  }
+  await greetWithVoice();
+}
+
+export function askLine(prompt) {
+  return new Promise((resolve) => {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    rl.question(prompt, (answer) => {
+      rl.close();
+      resolve(answer.trim());
+    });
+  });
+}