@settinghead/voxlert 0.3.5

package/src/commands/pack.js

@@ -0,0 +1,25 @@
+import { packList, packShow, packUse } from "./pack-helpers.js";
+
+export const packCommand = {
+  name: "pack",
+  aliases: [],
+  help: [
+    "  voxlert pack list           List available voice packs",
+    "  voxlert pack show           Show active pack details",
+    "  voxlert pack use <pack-id>  Switch active voice pack",
+  ],
+  skipSetupWizard: false,
+  skipUpgradeCheck: false,
+  async run(context) {
+    const [, sub, arg] = context.args;
+    if (sub === "list" || sub === "ls") {
+      packList();
+    } else if (sub === "show") {
+      packShow();
+    } else if (sub === "use") {
+      await packUse(arg);
+    } else {
+      packList();
+    }
+  },
+};

package/src/commands/setup.js

@@ -0,0 +1,13 @@
+export const setupCommand = {
+  name: "setup",
+  aliases: [],
+  help: [
+    "  voxlert setup               Interactive setup wizard (LLM, voice, TTS, hooks)",
+  ],
+  skipSetupWizard: true,
+  skipUpgradeCheck: false,
+  async run() {
+    const { runSetup } = await import("../setup.js");
+    await runSetup();
+  },
+};

package/src/commands/test.js

@@ -0,0 +1,14 @@
+import { testPipeline } from "./pack-helpers.js";
+
+export const testCommand = {
+  name: "test",
+  aliases: [],
+  help: [
+    "  voxlert test \"<text>\"       Run full pipeline: LLM -> TTS -> audio playback",
+  ],
+  skipSetupWizard: false,
+  skipUpgradeCheck: false,
+  async run(context) {
+    await testPipeline(context.args.slice(1).join(" "));
+  },
+};

package/src/commands/uninstall.js

@@ -0,0 +1,60 @@
+import { existsSync, rmSync } from "fs";
+import confirm from "@inquirer/confirm";
+import { unregisterHooks, removeSkill } from "../hooks.js";
+import { unregisterCursorHooks } from "../cursor-hooks.js";
+import { unregisterCodexNotify } from "../codex-config.js";
+import { STATE_DIR } from "../paths.js";
+
+async function runUninstall() {
+  console.log("Removing Voxlert hooks and skill...\n");
+
+  const claudeRemoved = unregisterHooks();
+  if (claudeRemoved > 0) {
+    console.log(`  Removed ${claudeRemoved} hook(s) from ~/.claude/settings.json`);
+  }
+
+  const cursorRemoved = unregisterCursorHooks();
+  if (cursorRemoved > 0) {
+    console.log(`  Removed ${cursorRemoved} hook(s) from ~/.cursor/hooks.json`);
+  }
+
+  const codexRemoved = unregisterCodexNotify();
+  if (codexRemoved) {
+    console.log("  Removed notify from ~/.codex/config.toml");
+  }
+
+  const skillRemoved = removeSkill();
+  if (skillRemoved) {
+    console.log("  Removed voxlert-config skill");
+  }
+
+  if (claudeRemoved === 0 && cursorRemoved === 0 && !codexRemoved && !skillRemoved) {
+    console.log("  No Voxlert hooks or skill were found.");
+  }
+
+  if (existsSync(STATE_DIR)) {
+    const removeData = await confirm({
+      message: `Remove config and cache (${STATE_DIR})?`,
+      default: false,
+    });
+    if (removeData) {
+      rmSync(STATE_DIR, { recursive: true });
+      console.log(`  Removed ${STATE_DIR}`);
+    }
+  }
+
+  console.log("\nUninstall complete. You can still run 'voxlert' if installed via npm; run 'npm uninstall -g @settinghead/voxlert' to remove the CLI.");
+}
+
+export const uninstallCommand = {
+  name: "uninstall",
+  aliases: [],
+  help: [
+    "  voxlert uninstall           Remove hooks from Claude Code, Cursor, and Codex, optionally config/cache",
+  ],
+  skipSetupWizard: true,
+  skipUpgradeCheck: false,
+  async run() {
+    await runUninstall();
+  },
+};

package/src/commands/version.js

@@ -0,0 +1,12 @@
+export const versionCommand = {
+  name: "version",
+  aliases: ["--version", "-v"],
+  help: [
+    "  voxlert --version           Show version",
+  ],
+  skipSetupWizard: true,
+  skipUpgradeCheck: false,
+  async run(context) {
+    console.log(context.pkg.version);
+  },
+};

package/src/commands/voice.js

@@ -0,0 +1,14 @@
+import { voicePick } from "./pack-helpers.js";
+
+export const voiceCommand = {
+  name: "voice",
+  aliases: ["voices"],
+  help: [
+    "  voxlert voice               Interactive voice pack picker",
+  ],
+  skipSetupWizard: false,
+  skipUpgradeCheck: false,
+  async run() {
+    await voicePick();
+  },
+};

package/src/commands/volume.js

@@ -0,0 +1,38 @@
+import { loadConfig, saveConfig } from "../config.js";
+import { askLine } from "./pack-helpers.js";
+
+async function setVolume(value) {
+  let num;
+  if (value == null || value === "") {
+    const config = loadConfig(process.cwd());
+    const current = Math.round((config.volume ?? 0.5) * 100);
+    const answer = await askLine(`Current volume: ${current}. Enter new volume (0-100): `);
+    num = Number(answer);
+  } else {
+    num = Number(value);
+  }
+
+  if (isNaN(num) || num < 0 || num > 100) {
+    console.error("Volume must be a number between 0 and 100.");
+    process.exit(1);
+  }
+
+  const config = loadConfig(process.cwd());
+  config.volume = num / 100;
+  saveConfig(config);
+  console.log(`Volume set to ${num}%`);
+}
+
+export const volumeCommand = {
+  name: "volume",
+  aliases: ["vol"],
+  help: [
+    "  voxlert volume              Show current volume and prompt for new value",
+    "  voxlert volume <0-100>      Set playback volume (0 = mute, 100 = max)",
+  ],
+  skipSetupWizard: false,
+  skipUpgradeCheck: false,
+  async run(context) {
+    await setVolume(context.args[1]);
+  },
+};

package/src/config.js

@@ -0,0 +1,230 @@
+import { existsSync, readFileSync, writeFileSync, mkdirSync, copyFileSync } from "fs";
+import { dirname, join } from "path";
+import { homedir } from "os";
+import { CONFIG_PATH, GLOBAL_USER_CONFIG_PATH, SCRIPT_DIR } from "./paths.js";
+
+// Hook event name -> internal category
+export const EVENT_MAP = {
+  Stop: "task.complete",
+  SessionStart: "session.start",
+  SessionEnd: "session.end",
+  UserPromptSubmit: "task.acknowledge",
+  PermissionRequest: "input.required",
+  PreCompact: "resource.limit",
+  PostToolUseFailure: "task.error",
+  Notification: "notification",
+};
+
+// Events where we call the LLM for a contextual phrase
+export const CONTEXTUAL_EVENTS = new Set(["Stop", "PostToolUseFailure"]);
+
+// Fallback phrases when LLM is unavailable or for non-contextual events
+export const FALLBACK_PHRASES = {
+  "session.start": [
+    "Systems online.",
+    "Awaiting orders",
+    "Station operational.",
+    "All systems nominal.",
+    "Ready for deployment.",
+  ],
+  "task.complete": [
+    "Mission complete.",
+    "Objective secured",
+    "All tasks fulfilled.",
+    "Operation completed.",
+    "Orders carried out.",
+    "Target achieved.",
+  ],
+  "task.acknowledge": [
+    "Orders received.",
+    "Request acknowledged",
+    "Operations initiated.",
+    "Command confirmed.",
+    "Directive understood.",
+  ],
+  "input.required": [
+    "Authorization required.",
+    "Input needed.",
+    "Clearance requested.",
+    "Decision awaited.",
+    "Confirmation required.",
+  ],
+  "resource.limit": [
+    "Memory capacity critical.",
+    "Resources nearly exhausted.",
+    "Buffer limit approached.",
+    "Context capacity strained.",
+    "Power reserves depleted.",
+  ],
+  "session.end": [
+    "Session terminated.",
+    "Connection closed.",
+    "Signing off.",
+    "Session ended.",
+    "Disconnected.",
+  ],
+  "task.error": [
+    "Operation failed.",
+    "Error detected.",
+    "Task aborted.",
+    "Execution error.",
+    "Failure reported.",
+  ],
+  notification: [
+    "Alert received.",
+    "Status change detected.",
+    "Notification logged.",
+  ],
+};
+
+// Fields allowed in per-directory and global-user config overrides
+const PROJECT_OVERRIDE_FIELDS = new Set([
+  "enabled",
+  "active_pack",
+  "volume",
+  "categories",
+  "collect_llm_data",
+  "max_cache_entries",
+  "prefix",
+  "tts_backend",
+  "qwen_tts_url",
+  "overlay",
+  "overlay_dismiss",
+  "overlay_style",
+  "logging",
+  "error_log",
+]);
+
+/**
+ * Walk up from cwd toward home directory looking for project config.
+ * Checks each directory for .voxlert.json then .voxlert/config.json.
+ * Returns the parsed config object from the nearest match, or null.
+ */
+function findProjectConfig(cwd) {
+  if (!cwd) return null;
+
+  const home = homedir();
+  let dir = cwd;
+
+  while (true) {
+    // Don't check $HOME itself — that's the global user tier
+    if (dir === home) break;
+
+    // Check .voxlert.json first (wins over .voxlert/config.json)
+    const dotFile = join(dir, ".voxlert.json");
+    try {
+      if (existsSync(dotFile)) {
+        return JSON.parse(readFileSync(dotFile, "utf-8"));
+      }
+    } catch {
+      // Malformed JSON — skip and keep walking
+    }
+
+    // Check .voxlert/config.json
+    const dirFile = join(dir, ".voxlert", "config.json");
+    try {
+      if (existsSync(dirFile)) {
+        return JSON.parse(readFileSync(dirFile, "utf-8"));
+      }
+    } catch {
+      // Malformed JSON — skip and keep walking
+    }
+
+    const parent = dirname(dir);
+    if (parent === dir) break; // filesystem root
+    dir = parent;
+  }
+
+  return null;
+}
+
+/**
+ * Load the global user config from ~/.voxlert/config.json.
+ * Returns empty object if missing or malformed.
+ */
+function loadGlobalUserConfig() {
+  try {
+    return JSON.parse(readFileSync(GLOBAL_USER_CONFIG_PATH, "utf-8"));
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Strip disallowed fields from an override config object.
+ */
+function filterOverrideFields(config) {
+  const filtered = {};
+  for (const key of Object.keys(config)) {
+    if (PROJECT_OVERRIDE_FIELDS.has(key)) {
+      filtered[key] = config[key];
+    }
+  }
+  return filtered;
+}
+
+/**
+ * Merge configs with shallow merge for most fields, deep merge for categories.
+ */
+function mergeConfigs(base, ...overrides) {
+  const result = { ...base };
+  for (const override of overrides) {
+    if (!override || typeof override !== "object") continue;
+    for (const [key, value] of Object.entries(override)) {
+      if (key === "categories" && typeof value === "object" && value !== null) {
+        result.categories = { ...(result.categories || {}), ...value };
+      } else {
+        result[key] = value;
+      }
+    }
+  }
+  return result;
+}
+
+/**
+ * Load config with 3-tier resolution:
+ *   1. Install-dir config.json (base)
+ *   2. ~/.voxlert/config.json (global user prefs, whitelist-filtered)
+ *   3. Nearest .voxlert.json / .voxlert/config.json (project override, whitelist-filtered)
+ *
+ * When called without cwd, behaves like the original (install config + global user only).
+ */
+export function loadConfig(cwd) {
+  // Tier 1: install-dir base config
+  let base;
+  try {
+    base = JSON.parse(readFileSync(CONFIG_PATH, "utf-8"));
+  } catch {
+    base = { enabled: true };
+  }
+
+  // Tier 2: global user config
+  const globalUser = filterOverrideFields(loadGlobalUserConfig());
+
+  // Tier 3: project config (nearest-only)
+  const project = cwd ? filterOverrideFields(findProjectConfig(cwd) || {}) : {};
+
+  return mergeConfigs(base, globalUser, project);
+}
+
+export function saveConfig(config) {
+  mkdirSync(dirname(CONFIG_PATH), { recursive: true });
+  writeFileSync(CONFIG_PATH, JSON.stringify(config, null, 2) + "\n");
+}
+
+/**
+ * Ensure config.json exists — creates from config.default.json template if missing.
+ * Returns the loaded config.
+ */
+export function ensureConfig() {
+  if (!existsSync(CONFIG_PATH)) {
+    const templatePath = join(SCRIPT_DIR, "config.default.json");
+    mkdirSync(dirname(CONFIG_PATH), { recursive: true });
+    if (existsSync(templatePath)) {
+      copyFileSync(templatePath, CONFIG_PATH);
+    } else {
+      writeFileSync(CONFIG_PATH, JSON.stringify({ enabled: true }, null, 2) + "\n");
+    }
+  }
+  return loadConfig();
+}

package/src/cost.js

@@ -0,0 +1,124 @@
+import { readFileSync, writeFileSync } from "fs";
+import { USAGE_FILE } from "./paths.js";
+
+// Fallback prices per 1M tokens [prompt, completion] in USD
+// Used only for old records missing usage.cost and when OpenRouter API is unreachable
+const FALLBACK_PRICES = {
+  "google/gemini-2.0-flash-001": [0.10, 0.40],
+  "openai/gpt-4o-mini": [0.15, 0.60],
+  "anthropic/claude-3.5-haiku": [0.80, 4.00],
+};
+
+let priceCache = null;
+let priceCacheTime = 0;
+const CACHE_TTL = 3600_000; // 1 hour
+
+async function fetchPricing() {
+  const now = Date.now();
+  if (priceCache && (now - priceCacheTime) < CACHE_TTL) {
+    return priceCache;
+  }
+  try {
+    const res = await fetch("https://openrouter.ai/api/v1/models");
+    if (!res.ok) throw new Error(`HTTP ${res.status}`);
+    const json = await res.json();
+    const table = {};
+    for (const model of json.data) {
+      const p = model.pricing;
+      if (p && p.prompt && p.completion) {
+        table[model.id] = [
+          parseFloat(p.prompt) * 1_000_000,
+          parseFloat(p.completion) * 1_000_000,
+        ];
+      }
+    }
+    priceCache = table;
+    priceCacheTime = now;
+    return table;
+  } catch {
+    return priceCache || FALLBACK_PRICES;
+  }
+}
+
+export function loadUsage() {
+  try {
+    const raw = readFileSync(USAGE_FILE, "utf-8").trim();
+    if (!raw) return [];
+    return raw.split("\n").map((line) => {
+      try {
+        return JSON.parse(line);
+      } catch {
+        return null;
+      }
+    }).filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
+export function resetUsage() {
+  writeFileSync(USAGE_FILE, "");
+}
+
+export async function formatCost() {
+  const entries = loadUsage();
+  if (!entries.length) {
+    return "No usage recorded yet.";
+  }
+
+  // Check if any entries need price-table estimation
+  const needsEstimation = entries.some((e) => e.cost == null);
+  const prices = needsEstimation ? await fetchPricing() : null;
+
+  const byModel = {};
+  let totalPrompt = 0;
+  let totalCompletion = 0;
+  let totalTokens = 0;
+
+  for (const e of entries) {
+    const m = e.model || "unknown";
+    if (!byModel[m]) byModel[m] = { prompt: 0, completion: 0, total: 0, calls: 0, cost: 0, estimated: 0 };
+    byModel[m].prompt += e.prompt_tokens || 0;
+    byModel[m].completion += e.completion_tokens || 0;
+    byModel[m].total += e.total_tokens || 0;
+    byModel[m].calls++;
+    if (e.cost != null) {
+      byModel[m].cost += e.cost;
+    } else {
+      // Estimate from price table for old records
+      const mp = prices[m];
+      if (mp) {
+        byModel[m].cost += ((e.prompt_tokens || 0) * mp[0] + (e.completion_tokens || 0) * mp[1]) / 1_000_000;
+        byModel[m].estimated++;
+      } else {
+        byModel[m].estimated++;
+      }
+    }
+    totalPrompt += e.prompt_tokens || 0;
+    totalCompletion += e.completion_tokens || 0;
+    totalTokens += e.total_tokens || 0;
+  }
+
+  const lines = ["Usage Summary", "=".repeat(40)];
+
+  let grandCost = 0;
+  let totalEstimated = 0;
+
+  for (const [model, stats] of Object.entries(byModel)) {
+    lines.push(`\nModel: ${model}`);
+    lines.push(`  Calls: ${stats.calls}`);
+    lines.push(`  Prompt tokens: ${stats.prompt.toLocaleString()}`);
+    lines.push(`  Completion tokens: ${stats.completion.toLocaleString()}`);
+    lines.push(`  Total tokens: ${stats.total.toLocaleString()}`);
+    lines.push(`  Cost: $${stats.cost.toFixed(6)}${stats.estimated ? ` (${stats.estimated} call${stats.estimated > 1 ? "s" : ""} estimated)` : ""}`);
+    grandCost += stats.cost;
+    totalEstimated += stats.estimated;
+  }
+
+  lines.push(`\n${"=".repeat(40)}`);
+  lines.push(`Total calls: ${entries.length}`);
+  lines.push(`Total tokens: ${totalTokens.toLocaleString()} (${totalPrompt.toLocaleString()} prompt + ${totalCompletion.toLocaleString()} completion)`);
+  lines.push(`Total cost: $${grandCost.toFixed(6)}${totalEstimated ? ` (${totalEstimated} call${totalEstimated > 1 ? "s" : ""} estimated from price table)` : ""}`);
+
+  return lines.join("\n");
+}

package/src/cursor-hooks.js

@@ -0,0 +1,93 @@
+import { readFileSync, writeFileSync, mkdirSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+
+const CURSOR_DIR = join(homedir(), ".cursor");
+const HOOKS_FILE = join(CURSOR_DIR, "hooks.json");
+
+const CURSOR_HOOK_EVENTS = [
+  "sessionStart",
+  "sessionEnd",
+  "stop",
+  "postToolUseFailure",
+  "preCompact",
+];
+
+const HOOK_ENTRY = (command) => ({
+  command,
+  timeout: 10,
+});
+
+function isVoxlertHook(entry) {
+  const cmd = (entry && entry.command) || "";
+  return typeof cmd === "string" && (cmd.includes("voxlert") || cmd.includes("cursor-hook"));
+}
+
+function loadHooks() {
+  try {
+    return JSON.parse(readFileSync(HOOKS_FILE, "utf-8"));
+  } catch {
+    return { version: 1, hooks: {} };
+  }
+}
+
+export function hasCursorHooks() {
+  const config = loadHooks();
+  if (!config.hooks || typeof config.hooks !== "object") return false;
+  return Object.values(config.hooks).some(
+    (entries) => Array.isArray(entries) && entries.some((entry) => isVoxlertHook(entry)),
+  );
+}
+
+/**
+ * Register Voxlert in ~/.cursor/hooks.json.
+ * Merges with existing hooks; does not remove other hooks.
+ * @param {string} command — e.g. "voxlert cursor-hook"
+ * @returns {number} number of hook events registered
+ */
+export function registerCursorHooks(command) {
+  mkdirSync(CURSOR_DIR, { recursive: true });
+  const config = loadHooks();
+  if (config.version === undefined) config.version = 1;
+  if (!config.hooks || typeof config.hooks !== "object") config.hooks = {};
+
+  let count = 0;
+  for (const event of CURSOR_HOOK_EVENTS) {
+    const existing = config.hooks[event];
+    const arr = Array.isArray(existing) ? existing : [];
+    const withoutUs = arr.filter((entry) => !isVoxlertHook(entry));
+    const entry = HOOK_ENTRY(command);
+    config.hooks[event] = [...withoutUs, entry];
+    count++;
+  }
+
+  writeFileSync(HOOKS_FILE, JSON.stringify(config, null, 2) + "\n");
+  return count;
+}
+
+/**
+ * Remove Voxlert hook entries from ~/.cursor/hooks.json.
+ * Leaves other hooks and the file intact.
+ * @returns {number} number of hook entries removed
+ */
+export function unregisterCursorHooks() {
+  try {
+    const config = loadHooks();
+    if (!config.hooks || typeof config.hooks !== "object") return 0;
+
+    let removed = 0;
+    for (const event of Object.keys(config.hooks)) {
+      const arr = config.hooks[event];
+      if (!Array.isArray(arr)) continue;
+      const before = arr.length;
+      config.hooks[event] = arr.filter((entry) => !isVoxlertHook(entry));
+      removed += before - config.hooks[event].length;
+      if (config.hooks[event].length === 0) delete config.hooks[event];
+    }
+
+    writeFileSync(HOOKS_FILE, JSON.stringify(config, null, 2) + "\n");
+    return removed;
+  } catch {
+    return 0;
+  }
+}

package/src/formats.js

@@ -0,0 +1,55 @@
+/**
+ * Shared format definitions for LLM phrase generation.
+ *
+ * Format  = structural rules (word count, grammar, what to include/omit)
+ * Style   = character personality (tone, vocabulary, examples)
+ *
+ * buildSystemPrompt() composes them into a single system prompt.
+ */
+
+const DEFAULT_STYLE =
+  "You are a status report assistant.";
+
+const FORMATS = {
+  "status-report": [
+    "Respond with ONLY 2-8 words as a brief status report.",
+    "The phrase MUST end with a past participle OR adjective (but not both).",
+    "Before the final word, state WHAT was done. If you can clearly infer WHY it exists — the purpose or goal — include it (e.g. 'item for purpose adjective'). If the purpose is not obvious, omit it and just describe the action.",
+    "Do NOT fabricate or guess a purpose. Only include 'for …' when the intent is clearly evident from context.",
+    "No punctuation. No quotes. No explanation.",
+  ].join(" "),
+};
+
+/**
+ * Format examples array into prompt text.
+ * Each example: { content, format?, response }
+ *
+ * @param {Array|null} examples
+ * @param {string} formatId - only include examples matching this format
+ * @returns {string} Formatted examples block, or empty string
+ */
+function formatExamples(examples, formatId) {
+  if (!Array.isArray(examples) || examples.length === 0) return "";
+  const matching = examples.filter(
+    (ex) => ex.content && ex.response && (!ex.format || ex.format === formatId),
+  );
+  if (matching.length === 0) return "";
+  const lines = matching.map(
+    (ex) => `"${ex.content}" → ${ex.response}`,
+  );
+  return "\n\nExamples:\n" + lines.join("\n");
+}
+
+/**
+ * Compose a full system prompt from a style string, format id, and examples.
+ *
+ * @param {string|null} style     - Character personality text (null → default neutral)
+ * @param {string}      formatId  - Format key (default: "status-report")
+ * @param {Array|null}  examples  - Few-shot examples from pack.json
+ * @returns {string} Complete system prompt
+ */
+export function buildSystemPrompt(style, formatId = "status-report", examples = null) {
+  const format = FORMATS[formatId] || FORMATS["status-report"];
+  const s = style || DEFAULT_STYLE;
+  return format + "\n\n" + s + formatExamples(examples, formatId);
+}