Skip to content

Voice-to-text dictation app with local (Nvidia Parakeet/Whisper) and cloud models (BYOK). Privacy-first and available cross-platform.

test: port unit coverage for hotkey, URL, cache, and formatting utils from #440

Gabriel Stein499f1f7838d4
diff --git a/src/utils/SecureCache.ts b/src/utils/SecureCache.ts
index b1db80738..260597ac6 100644
--- a/src/utils/SecureCache.ts
+++ b/src/utils/SecureCache.ts
@@ -1,4 +1,4 @@
-import { CACHE_CONFIG } from "../config/constants";
+import { CACHE_CONFIG } from "../config/constants.ts";
interface CacheEntry<T> {
value: T;
diff --git a/src/utils/hotkeyValidator.ts b/src/utils/hotkeyValidator.ts
index 956850dc1..fcc229f0c 100644
--- a/src/utils/hotkeyValidator.ts
+++ b/src/utils/hotkeyValidator.ts
@@ -3,7 +3,7 @@ import {
isGlobeLikeHotkey,
isMouseButtonHotkey,
parseHotkeyList,
-} from "./hotkeys";
+} from "./hotkeys.ts";
export type Platform = "darwin" | "win32" | "linux";
diff --git a/src/utils/hotkeys.ts b/src/utils/hotkeys.ts
index d4eee3d89..889b44ce8 100644
--- a/src/utils/hotkeys.ts
+++ b/src/utils/hotkeys.ts
@@ -3,7 +3,7 @@
* Supports both single keys and compound hotkeys (e.g., "CommandOrControl+Shift+K").
*/
-import { getPlatform, type Platform } from "./platform";
+import { getPlatform, type Platform } from "./platform.ts";
export function isGlobeLikeHotkey(hotkey: string): boolean {
return hotkey === "GLOBE" || hotkey === "Fn";
diff --git a/test/helpers/apiBaseUrl.test.js b/test/helpers/apiBaseUrl.test.js
new file mode 100644
index 000000000..d479b543e
--- /dev/null
+++ b/test/helpers/apiBaseUrl.test.js
@@ -0,0 +1,102 @@
+const test = require("node:test");
+const assert = require("node:assert/strict");
+
+// Requires Node's native TypeScript type-stripping (Node >= 22.6 with
+// --experimental-strip-types, on by default in Node 23.6+/24). CI runs Node 24.
+
+const load = () => import("../../src/config/constants.ts");
+
+test("empty or blank base URLs normalize to an empty string", async () => {
+ const { normalizeBaseUrl } = await load();
+
+ assert.equal(normalizeBaseUrl(null), "");
+ assert.equal(normalizeBaseUrl(undefined), "");
+ assert.equal(normalizeBaseUrl(""), "");
+ assert.equal(normalizeBaseUrl(" "), "");
+});
+
+test("trailing slashes are stripped", async () => {
+ const { normalizeBaseUrl } = await load();
+
+ assert.equal(normalizeBaseUrl("https://api.example.com/"), "https://api.example.com");
+ assert.equal(normalizeBaseUrl("https://api.example.com///"), "https://api.example.com");
+});
+
+test("pasted endpoint URLs are reduced to their base — users paste full completion URLs from provider docs", async () => {
+ const { normalizeBaseUrl } = await load();
+
+ assert.equal(
+ normalizeBaseUrl("https://api.example.com/v1/chat/completions"),
+ "https://api.example.com/v1"
+ );
+ assert.equal(
+ normalizeBaseUrl("https://api.example.com/chat/completions"),
+ "https://api.example.com"
+ );
+ assert.equal(
+ normalizeBaseUrl("https://api.example.com/v1/responses"),
+ "https://api.example.com/v1"
+ );
+ assert.equal(normalizeBaseUrl("https://api.example.com/v1/models"), "https://api.example.com/v1");
+ assert.equal(
+ normalizeBaseUrl("https://api.example.com/v1/audio/transcriptions"),
+ "https://api.example.com/v1"
+ );
+ assert.equal(
+ normalizeBaseUrl("https://api.example.com/audio/transcriptions"),
+ "https://api.example.com"
+ );
+ assert.equal(
+ normalizeBaseUrl("https://api.example.com/v1/audio/translations"),
+ "https://api.example.com/v1"
+ );
+});
+
+test("a clean base URL passes through unchanged", async () => {
+ const { normalizeBaseUrl } = await load();
+
+ assert.equal(normalizeBaseUrl("https://api.openai.com/v1"), "https://api.openai.com/v1");
+});
+
+test("suffix matching is case-insensitive and canonicalizes to lowercase /v1", async () => {
+ const { normalizeBaseUrl } = await load();
+
+ assert.equal(
+ normalizeBaseUrl("https://api.example.com/V1/Chat/Completions"),
+ "https://api.example.com/v1"
+ );
+});
+
+test("buildApiUrl joins base and path, adding the leading slash when missing", async () => {
+ const { buildApiUrl } = await load();
+
+ assert.equal(
+ buildApiUrl("https://api.openai.com/v1", "/responses"),
+ "https://api.openai.com/v1/responses"
+ );
+ assert.equal(
+ buildApiUrl("https://api.openai.com/v1", "responses"),
+ "https://api.openai.com/v1/responses"
+ );
+});
+
+test("buildApiUrl falls back to the OpenAI default when the base is empty", async () => {
+ const { buildApiUrl } = await load();
+
+ assert.equal(buildApiUrl("", "/responses"), "https://api.openai.com/v1/responses");
+});
+
+test("buildApiUrl normalizes a pasted endpoint URL before appending", async () => {
+ const { buildApiUrl } = await load();
+
+ assert.equal(
+ buildApiUrl("https://api.example.com/v1/chat/completions", "/responses"),
+ "https://api.example.com/v1/responses"
+ );
+});
+
+test("buildApiUrl with an empty path returns just the normalized base", async () => {
+ const { buildApiUrl } = await load();
+
+ assert.equal(buildApiUrl("https://api.openai.com/v1", ""), "https://api.openai.com/v1");
+});
diff --git a/test/helpers/correctionLearner.test.js b/test/helpers/correctionLearner.test.js
new file mode 100644
index 000000000..d8ef8ec7f
--- /dev/null
+++ b/test/helpers/correctionLearner.test.js
@@ -0,0 +1,55 @@
+const test = require("node:test");
+const assert = require("node:assert/strict");
+
+const { extractCorrections } = require("../../src/utils/correctionLearner.js");
+
+test("null or empty inputs yield no corrections", () => {
+ assert.deepEqual(extractCorrections(null, "hello", []), []);
+ assert.deepEqual(extractCorrections("hello", null, []), []);
+ assert.deepEqual(extractCorrections("", "hello", []), []);
+ assert.deepEqual(extractCorrections("hello", "", []), []);
+});
+
+test("identical texts yield no corrections", () => {
+ assert.deepEqual(extractCorrections("hello world", "hello world", []), []);
+});
+
+test("a phonetic mishearing fixed by the user is learned", () => {
+ // "Shunade" is a plausible transcription mishearing of "Sinead"
+ const result = extractCorrections("Hey Shunade how are you", "Hey Sinead how are you", []);
+ assert.ok(result.includes("Sinead"));
+});
+
+test("corrections already in the dictionary are not re-learned, case-insensitively", () => {
+ const original = "Hey Shunade how are you";
+ const edited = "Hey Sinead how are you";
+
+ assert.ok(!extractCorrections(original, edited, ["Sinead"]).includes("Sinead"));
+ assert.ok(!extractCorrections(original, edited, ["sinead"]).includes("Sinead"));
+});
+
+test("a wholesale rewrite is not mistaken for corrections", () => {
+ const result = extractCorrections("the cat sat on the mat", "a dog stood under a rug", []);
+ assert.deepEqual(result, []);
+});
+
+test("very short replacements are ignored — two-letter words are edits, not vocabulary", () => {
+ const result = extractCorrections("I went to see XX today", "I went to see Al today", []);
+ assert.ok(!result.includes("Al"));
+});
+
+test("unrelated word swaps are filtered by edit distance — cat to elephant is a rewrite, not a mishearing", () => {
+ const result = extractCorrections("I saw a cat yesterday", "I saw a elephant yesterday", []);
+ assert.ok(!result.includes("elephant"));
+});
+
+test("a non-array dictionary is tolerated", () => {
+ const result = extractCorrections("Hey Shunade", "Hey Sinead", null);
+ assert.ok(result.includes("Sinead"));
+});
+
+test("the same correction appearing twice is only learned once", () => {
+ const result = extractCorrections("Shunade said hi to Shunade", "Sinead said hi to Sinead", []);
+ const sinead = result.filter((w) => w.toLowerCase() === "sinead");
+ assert.ok(sinead.length <= 1);
+});
diff --git a/test/helpers/dateGroupFormatting.test.js b/test/helpers/dateGroupFormatting.test.js
new file mode 100644
index 000000000..16dce1f41
--- /dev/null
+++ b/test/helpers/dateGroupFormatting.test.js
@@ -0,0 +1,72 @@
+const test = require("node:test");
+const assert = require("node:assert/strict");
+
+// Requires Node's native TypeScript type-stripping (Node >= 22.6 with
+// --experimental-strip-types, on by default in Node 23.6+/24). CI runs Node 24.
+
+const load = () => import("../../src/utils/dateFormatting.ts");
+
+const t = (key) =>
+ ({
+ "controlPanel.history.dateGroups.today": "Today",
+ "controlPanel.history.dateGroups.yesterday": "Yesterday",
+ "upcoming.tomorrow": "Tomorrow",
+ })[key] || key;
+
+// Local-time constructors keep these assertions timezone-independent.
+const NOON_JUNE_15 = new Date(2024, 5, 15, 12, 0, 0).getTime();
+
+test("SQLite timestamps without a zone are treated as UTC", async () => {
+ const { normalizeDbDate } = await load();
+
+ const result = normalizeDbDate("2024-01-15 10:30:00");
+ assert.ok(result instanceof Date);
+ assert.ok(result.toISOString().startsWith("2024-01-15T10:30:00"));
+
+ const alreadyUtc = normalizeDbDate("2024-01-15T10:30:00Z");
+ assert.equal(alreadyUtc.toISOString(), "2024-01-15T10:30:00.000Z");
+});
+
+test("history groups label today's and yesterday's dates by calendar day", async (t2) => {
+ const { formatDateGroup } = await load();
+ t2.mock.timers.enable({ apis: ["Date"], now: NOON_JUNE_15 });
+
+ assert.equal(formatDateGroup(new Date(2024, 5, 15, 8), t), "Today");
+ assert.equal(formatDateGroup(new Date(2024, 5, 14, 20), t), "Yesterday");
+});
+
+test("history groups fall back to a formatted date for older days", async (t2) => {
+ const { formatDateGroup } = await load();
+ t2.mock.timers.enable({ apis: ["Date"], now: NOON_JUNE_15 });
+
+ const result = formatDateGroup(new Date(2024, 0, 10, 12), t);
+ assert.ok(result);
+ assert.notEqual(result, "Today");
+ assert.notEqual(result, "Yesterday");
+});
+
+test("string dates are accepted", async (t2) => {
+ const { formatDateGroup } = await load();
+ t2.mock.timers.enable({ apis: ["Date"], now: NOON_JUNE_15 });
+
+ // No zone suffix: parsed as local time, same day as the mocked clock.
+ assert.equal(formatDateGroup("2024-06-15T08:00:00", t), "Today");
+});
+
+test("upcoming groups label today and tomorrow by calendar day", async (t2) => {
+ const { formatUpcomingDateGroup } = await load();
+ t2.mock.timers.enable({ apis: ["Date"], now: NOON_JUNE_15 });
+
+ assert.equal(formatUpcomingDateGroup(new Date(2024, 5, 15, 8), t), "Today");
+ assert.equal(formatUpcomingDateGroup(new Date(2024, 5, 16, 8), t), "Tomorrow");
+});
+
+test("upcoming groups fall back to a formatted date further out", async (t2) => {
+ const { formatUpcomingDateGroup } = await load();
+ t2.mock.timers.enable({ apis: ["Date"], now: NOON_JUNE_15 });
+
+ const result = formatUpcomingDateGroup(new Date(2024, 5, 20, 12), t);
+ assert.ok(result);
+ assert.notEqual(result, "Today");
+ assert.notEqual(result, "Tomorrow");
+});
diff --git a/test/helpers/fileRetryStrategy.test.js b/test/helpers/fileRetryStrategy.test.js
new file mode 100644
index 000000000..3aa7bdf9f
--- /dev/null
+++ b/test/helpers/fileRetryStrategy.test.js
@@ -0,0 +1,33 @@
+const test = require("node:test");
+const assert = require("node:assert/strict");
+
+// Requires Node's native TypeScript type-stripping (Node >= 22.6 with
+// --experimental-strip-types, on by default in Node 23.6+/24). CI runs Node 24.
+
+const load = () => import("../../src/utils/retry.ts");
+
+test("transient filesystem errors retry — antivirus and indexers briefly lock temp audio files", async () => {
+ const { createFileRetryStrategy } = await load();
+ const { shouldRetry } = createFileRetryStrategy();
+
+ assert.equal(shouldRetry({ code: "EBUSY" }), true);
+ assert.equal(shouldRetry({ code: "ENOENT" }), true);
+ assert.equal(shouldRetry({ code: "EPERM" }), true);
+ assert.equal(shouldRetry({ code: "EAGAIN" }), true);
+});
+
+test("permanent filesystem errors do not retry", async () => {
+ const { createFileRetryStrategy } = await load();
+ const { shouldRetry } = createFileRetryStrategy();
+
+ assert.equal(shouldRetry({ code: "EACCES" }), false);
+ assert.equal(shouldRetry({ code: "EISDIR" }), false);
+});
+
+test("the strategy bounds its own retries and delay", async () => {
+ const { createFileRetryStrategy } = await load();
+ const strategy = createFileRetryStrategy();
+
+ assert.equal(strategy.maxRetries, 2);
+ assert.equal(strategy.initialDelay, 500);
+});
diff --git a/test/helpers/formatBytes.test.js b/test/helpers/formatBytes.test.js
new file mode 100644
index 000000000..13fe94166
--- /dev/null
+++ b/test/helpers/formatBytes.test.js
@@ -0,0 +1,35 @@
+const test = require("node:test");
+const assert = require("node:assert/strict");
+
+// Requires Node's native TypeScript type-stripping (Node >= 22.6 with
+// --experimental-strip-types, on by default in Node 23.6+/24). CI runs Node 24.
+
+const load = () => import("../../src/utils/formatBytes.ts");
+
+test("zero and sub-kilobyte values format as Bytes", async () => {
+ const { formatBytes } = await load();
+
+ assert.equal(formatBytes(0), "0 Bytes");
+ assert.equal(formatBytes(1), "1 Bytes");
+ assert.equal(formatBytes(500), "500 Bytes");
+});
+
+test("unit boundaries land on whole units — model download sizes must read cleanly", async () => {
+ const { formatBytes } = await load();
+
+ assert.equal(formatBytes(1024), "1 KB");
+ assert.equal(formatBytes(1024 * 1024), "1 MB");
+ assert.equal(formatBytes(1024 * 1024 * 1024), "1 GB");
+ assert.equal(formatBytes(1024 ** 4), "1 TB");
+ assert.equal(formatBytes(5.5 * 1024 * 1024 * 1024), "5.5 GB");
+});
+
+test("fractional values respect the decimals parameter, with negatives clamped to zero", async () => {
+ const { formatBytes } = await load();
+
+ assert.equal(formatBytes(1536), "1.5 KB");
+ assert.equal(formatBytes(1536, 0), "2 KB");
+ assert.equal(formatBytes(1536, 1), "1.5 KB");
+ assert.equal(formatBytes(1536, 3), "1.5 KB");
+ assert.equal(formatBytes(1536, -1), "2 KB");
+});
diff --git a/test/helpers/hotkeyLabels.test.js b/test/helpers/hotkeyLabels.test.js
new file mode 100644
index 000000000..5e47767bb
--- /dev/null
+++ b/test/helpers/hotkeyLabels.test.js
@@ -0,0 +1,125 @@
+const test = require("node:test");
+const assert = require("node:assert/strict");
+
+// Requires Node's native TypeScript type-stripping (Node >= 22.6 with
+// --experimental-strip-types, on by default in Node 23.6+/24). CI runs Node 24.
+
+const load = () => import("../../src/utils/hotkeys.ts");
+
+test("isGlobeLikeHotkey matches exactly GLOBE and Fn, nothing else", async () => {
+ const { isGlobeLikeHotkey } = await load();
+
+ assert.equal(isGlobeLikeHotkey("GLOBE"), true);
+ assert.equal(isGlobeLikeHotkey("Fn"), true);
+ assert.equal(isGlobeLikeHotkey("F1"), false);
+ assert.equal(isGlobeLikeHotkey("globe"), false);
+ assert.equal(isGlobeLikeHotkey("fn"), false);
+ assert.equal(isGlobeLikeHotkey(""), false);
+});
+
+test("empty input formats to an empty label", async () => {
+ const { formatHotkeyLabelForPlatform } = await load();
+
+ assert.equal(formatHotkeyLabelForPlatform("", "darwin"), "");
+ assert.equal(formatHotkeyLabelForPlatform(" ", "darwin"), "");
+});
+
+test("globe-like hotkeys display as Globe/Fn on every platform", async () => {
+ const { formatHotkeyLabelForPlatform } = await load();
+
+ assert.equal(formatHotkeyLabelForPlatform("GLOBE", "darwin"), "Globe/Fn");
+ assert.equal(formatHotkeyLabelForPlatform("Fn", "win32"), "Globe/Fn");
+});
+
+test("mouse button hotkeys display with spaces", async () => {
+ const { formatHotkeyLabelForPlatform } = await load();
+
+ assert.equal(formatHotkeyLabelForPlatform("MouseButton4", "darwin"), "Mouse Button 4");
+ assert.equal(formatHotkeyLabelForPlatform("MouseButton5", "darwin"), "Mouse Button 5");
+});
+
+test("the same stored accelerator renders per platform: Cmd on macOS, Ctrl on Windows", async () => {
+ const { formatHotkeyLabelForPlatform } = await load();
+
+ assert.equal(formatHotkeyLabelForPlatform("CommandOrControl+K", "darwin"), "Cmd+K");
+ assert.equal(formatHotkeyLabelForPlatform("CommandOrControl+K", "win32"), "Ctrl+K");
+});
+
+test("Alt displays as Option on macOS and stays Alt on Windows", async () => {
+ const { formatHotkeyLabelForPlatform } = await load();
+
+ assert.equal(formatHotkeyLabelForPlatform("Alt+R", "darwin"), "Option+R");
+ assert.equal(formatHotkeyLabelForPlatform("Alt+R", "win32"), "Alt+R");
+});
+
+test("Super/Meta display as Cmd on macOS, Win on Windows, Super on Linux", async () => {
+ const { formatHotkeyLabelForPlatform } = await load();
+
+ assert.equal(formatHotkeyLabelForPlatform("Super+K", "darwin"), "Cmd+K");
+ assert.equal(formatHotkeyLabelForPlatform("Meta+K", "darwin"), "Cmd+K");
+ assert.equal(formatHotkeyLabelForPlatform("Super+K", "win32"), "Win+K");
+ assert.equal(formatHotkeyLabelForPlatform("Meta+K", "win32"), "Win+K");
+ assert.equal(formatHotkeyLabelForPlatform("Super+K", "linux"), "Super+K");
+ assert.equal(formatHotkeyLabelForPlatform("Meta+K", "linux"), "Super+K");
+});
+
+test("right-side single modifiers get spelled-out platform-aware labels", async () => {
+ const { formatHotkeyLabelForPlatform } = await load();
+
+ assert.equal(formatHotkeyLabelForPlatform("RightOption", "darwin"), "Right Option");
+ assert.equal(formatHotkeyLabelForPlatform("RightOption", "win32"), "Right Alt");
+ assert.equal(formatHotkeyLabelForPlatform("RightSuper", "win32"), "Right Win");
+ assert.equal(formatHotkeyLabelForPlatform("RightCommand", "darwin"), "Right Cmd");
+});
+
+test("single keys pass through unchanged", async () => {
+ const { formatHotkeyLabelForPlatform } = await load();
+
+ assert.equal(formatHotkeyLabelForPlatform("`", "darwin"), "`");
+ assert.equal(formatHotkeyLabelForPlatform("F8", "win32"), "F8");
+});
+
+test("parseHotkey splits modifiers from the base key", async () => {
+ const { parseHotkey } = await load();
+
+ assert.deepEqual(parseHotkey("CommandOrControl+Shift+K"), {
+ modifiers: ["CommandOrControl", "Shift"],
+ baseKey: "K",
+ });
+ assert.deepEqual(parseHotkey("Alt+R"), { modifiers: ["Alt"], baseKey: "R" });
+ assert.deepEqual(parseHotkey("F8"), { modifiers: [], baseKey: "F8" });
+ assert.deepEqual(parseHotkey(""), { modifiers: [], baseKey: "" });
+ assert.deepEqual(parseHotkey(null), { modifiers: [], baseKey: "" });
+});
+
+test("isCompoundHotkey is true only when modifiers are present", async () => {
+ const { isCompoundHotkey } = await load();
+
+ assert.equal(isCompoundHotkey("Ctrl+Shift+K"), true);
+ assert.equal(isCompoundHotkey("Alt+R"), true);
+ assert.equal(isCompoundHotkey("F8"), false);
+ assert.equal(isCompoundHotkey("GLOBE"), false);
+ assert.equal(isCompoundHotkey(""), false);
+ assert.equal(isCompoundHotkey(null), false);
+});
+
+test("isValidHotkeyFormat accepts single keys, globe, mouse buttons, and well-formed combos", async () => {
+ const { isValidHotkeyFormat } = await load();
+
+ assert.equal(isValidHotkeyFormat("GLOBE"), true);
+ assert.equal(isValidHotkeyFormat("Fn"), true);
+ assert.equal(isValidHotkeyFormat("MouseButton4"), true);
+ assert.equal(isValidHotkeyFormat("`"), true);
+ assert.equal(isValidHotkeyFormat("A"), true);
+ assert.equal(isValidHotkeyFormat("Ctrl+K"), true);
+ assert.equal(isValidHotkeyFormat("Alt+Shift+F9"), true);
+});
+
+test("isValidHotkeyFormat rejects empty input and combos with empty parts", async () => {
+ const { isValidHotkeyFormat } = await load();
+
+ assert.equal(isValidHotkeyFormat(""), false);
+ assert.equal(isValidHotkeyFormat(" "), false);
+ assert.equal(isValidHotkeyFormat("Ctrl+"), false);
+ assert.equal(isValidHotkeyFormat("+K"), false);
+});
diff --git a/test/helpers/hotkeyValidation.test.js b/test/helpers/hotkeyValidation.test.js
new file mode 100644
index 000000000..94f287a9b
--- /dev/null
+++ b/test/helpers/hotkeyValidation.test.js
@@ -0,0 +1,175 @@
+const test = require("node:test");
+const assert = require("node:assert/strict");
+
+// Requires Node's native TypeScript type-stripping (Node >= 22.6 with
+// --experimental-strip-types, on by default in Node 23.6+/24). CI runs Node 24.
+
+const load = () => import("../../src/utils/hotkeyValidator.ts");
+
+test("empty and whitespace-only input is rejected", async () => {
+ const { validateHotkey } = await load();
+
+ assert.equal(validateHotkey("", "darwin").valid, false);
+ assert.equal(validateHotkey(" ", "darwin").valid, false);
+});
+
+test("GLOBE/Fn is macOS-only — accepting it elsewhere would register a key the OS doesn't have", async () => {
+ const { validateHotkey } = await load();
+
+ assert.equal(validateHotkey("GLOBE", "darwin").valid, true);
+ assert.equal(validateHotkey("Fn", "darwin").valid, true);
+
+ const win = validateHotkey("GLOBE", "win32");
+ assert.equal(win.valid, false);
+ assert.equal(win.errorCode, "INVALID_GLOBE");
+});
+
+test("mouse button hotkeys are macOS-only and cannot combine with keyboard keys", async () => {
+ const { validateHotkey } = await load();
+
+ assert.equal(validateHotkey("MouseButton4", "darwin").valid, true);
+ assert.equal(validateHotkey("MouseButton5", "win32").valid, false);
+ assert.equal(validateHotkey("Control+MouseButton4", "darwin").valid, false);
+});
+
+test("shortcuts with more than three keys are rejected", async () => {
+ const { validateHotkey } = await load();
+
+ const result = validateHotkey("Ctrl+Alt+Shift+K", "win32");
+ assert.equal(result.valid, false);
+ assert.equal(result.errorCode, "TOO_MANY_KEYS");
+});
+
+test("a bare letter needs a modifier — otherwise typing that letter anywhere would trigger dictation", async () => {
+ const { validateHotkey } = await load();
+
+ const result = validateHotkey("K", "win32");
+ assert.equal(result.valid, false);
+ assert.equal(result.errorCode, "NO_MODIFIER_OR_SPECIAL");
+});
+
+test("standalone special keys are allowed without a modifier", async () => {
+ const { validateHotkey } = await load();
+
+ assert.equal(validateHotkey("F8", "darwin").valid, true);
+ assert.equal(validateHotkey("Space", "win32").valid, true);
+ assert.equal(validateHotkey("Esc", "linux").valid, true);
+});
+
+test("mixing left and right versions of the same modifier is rejected", async () => {
+ const { validateHotkey } = await load();
+
+ const result = validateHotkey("LeftCtrl+RightCtrl+K", "win32");
+ assert.equal(result.valid, false);
+ assert.equal(result.errorCode, "LEFT_RIGHT_MIX");
+});
+
+test("a single left-side modifier cannot be a hotkey, but a right-side one can (except on Linux)", async () => {
+ const { validateHotkey } = await load();
+
+ const left = validateHotkey("Control", "win32");
+ assert.equal(left.valid, false);
+ assert.equal(left.errorCode, "LEFT_MODIFIER_ONLY");
+
+ assert.equal(validateHotkey("RightOption", "darwin").valid, true);
+ assert.equal(validateHotkey("RightAlt", "win32").valid, true);
+
+ // Right-side single modifiers need native listeners, which don't exist on Linux.
+ const linux = validateHotkey("RightAlt", "linux");
+ assert.equal(linux.valid, false);
+ assert.equal(linux.errorCode, "LEFT_MODIFIER_ONLY");
+});
+
+test("two-modifier combos without a base key are valid", async () => {
+ const { validateHotkey } = await load();
+
+ assert.equal(validateHotkey("Control+Alt", "win32").valid, true);
+ assert.equal(validateHotkey("Control+Super", "linux").valid, true);
+});
+
+test("duplicates are detected after normalization, so Ctrl+K collides with a stored Control+K", async () => {
+ const { validateHotkey } = await load();
+
+ const result = validateHotkey("Ctrl+K", "win32", ["Control+K"]);
+ assert.equal(result.valid, false);
+ assert.equal(result.errorCode, "DUPLICATE");
+});
+
+test("system-reserved shortcuts are rejected — registering them would break copy/paste or window switching OS-wide", async () => {
+ const { validateHotkey } = await load();
+
+ for (const [hotkey, platform] of [
+ ["Command+C", "darwin"],
+ ["Control+C", "win32"],
+ ["Control+C", "linux"],
+ ["Alt+Tab", "win32"],
+ ["Alt+F4", "win32"],
+ ["Control+Alt+Delete", "linux"],
+ ]) {
+ const result = validateHotkey(hotkey, platform);
+ assert.equal(result.valid, false, `${hotkey} on ${platform} should be reserved`);
+ assert.equal(result.errorCode, "RESERVED");
+ }
+});
+
+test("reserved shortcuts match after normalization, so Cmd+c and Command+C are equally rejected", async () => {
+ const { validateHotkey } = await load();
+
+ const result = validateHotkey("Cmd+c", "darwin");
+ assert.equal(result.valid, false);
+ assert.equal(result.errorCode, "RESERVED");
+});
+
+test("ordinary compound shortcuts pass validation", async () => {
+ const { validateHotkey } = await load();
+
+ assert.equal(validateHotkey("Control+Shift+K", "darwin").valid, true);
+ assert.equal(validateHotkey("Alt+F7", "win32").valid, true);
+ assert.equal(validateHotkey("Control+Super+K", "linux").valid, true);
+});
+
+test("a comma-separated slot validates each entry and fails on the first bad one", async () => {
+ const { validateHotkey } = await load();
+
+ assert.equal(validateHotkey("F8,Control+Shift+K", "win32").valid, true);
+
+ const result = validateHotkey("F8,GLOBE", "win32");
+ assert.equal(result.valid, false);
+ assert.equal(result.errorCode, "INVALID_GLOBE");
+});
+
+test("normalizeHotkey resolves CommandOrControl per platform", async () => {
+ const { normalizeHotkey } = await load();
+
+ assert.equal(normalizeHotkey("CommandOrControl+K", "darwin"), "Command+K");
+ assert.equal(normalizeHotkey("CommandOrControl+K", "win32"), "Control+K");
+ assert.equal(normalizeHotkey("CmdOrCtrl+K", "darwin"), "Command+K");
+ assert.equal(normalizeHotkey("CmdOrCtrl+K", "win32"), "Control+K");
+});
+
+test("normalizeHotkey maps Option to Alt and Super/Win/Meta to the platform modifier", async () => {
+ const { normalizeHotkey } = await load();
+
+ assert.equal(normalizeHotkey("Option+R", "darwin"), "Alt+R");
+ assert.equal(normalizeHotkey("Super+K", "darwin"), "Command+K");
+ assert.equal(normalizeHotkey("Win+K", "win32"), "Super+K");
+ assert.equal(normalizeHotkey("Meta+K", "linux"), "Super+K");
+});
+
+test("normalizeHotkey sorts modifiers into one canonical order so duplicate detection can compare strings", async () => {
+ const { normalizeHotkey } = await load();
+
+ assert.equal(normalizeHotkey("Shift+Control+K", "win32"), "Control+Shift+K");
+ assert.equal(normalizeHotkey("Shift+Alt+Control+K", "win32"), "Control+Alt+Shift+K");
+});
+
+test("normalizeHotkey canonicalizes key token spellings", async () => {
+ const { normalizeHotkey } = await load();
+
+ assert.equal(normalizeHotkey("Ctrl+ArrowLeft", "win32"), "Control+Left");
+ assert.equal(normalizeHotkey("Ctrl+Escape", "win32"), "Control+Esc");
+ assert.equal(normalizeHotkey("Ctrl+pgup", "win32"), "Control+PageUp");
+ assert.equal(normalizeHotkey("Ctrl+k", "win32"), "Control+K");
+ assert.equal(normalizeHotkey("Ctrl+f9", "win32"), "Control+F9");
+ assert.equal(normalizeHotkey("", "darwin"), "");
+});
diff --git a/test/helpers/secureCache.test.js b/test/helpers/secureCache.test.js
new file mode 100644
index 000000000..ec825e8cf
--- /dev/null
+++ b/test/helpers/secureCache.test.js
@@ -0,0 +1,111 @@
+const test = require("node:test");
+const assert = require("node:assert/strict");
+
+// Requires Node's native TypeScript type-stripping (Node >= 22.6 with
+// --experimental-strip-types, on by default in Node 23.6+/24). CI runs Node 24.
+
+const load = () => import("../../src/utils/SecureCache.ts");
+
+test("stores and retrieves values, returning undefined for missing keys", async () => {
+ const { SecureCache } = await load();
+ const cache = new SecureCache(60000);
+
+ cache.set("key1", "value1");
+ assert.equal(cache.get("key1"), "value1");
+ assert.equal(cache.get("nonexistent"), undefined);
+});
+
+test("entries expire after the TTL and survive until just before it", async (t) => {
+ const { SecureCache } = await load();
+ t.mock.timers.enable({ apis: ["Date"] });
+
+ const cache = new SecureCache(1000);
+ cache.set("key1", "value1");
+
+ t.mock.timers.tick(999);
+ assert.equal(cache.get("key1"), "value1");
+
+ t.mock.timers.tick(2);
+ assert.equal(cache.get("key1"), undefined);
+});
+
+test("has() reflects liveness, not mere presence", async (t) => {
+ const { SecureCache } = await load();
+ t.mock.timers.enable({ apis: ["Date"] });
+
+ const cache = new SecureCache(1000);
+ cache.set("key1", "value1");
+ assert.equal(cache.has("key1"), true);
+
+ t.mock.timers.tick(1001);
+ assert.equal(cache.has("key1"), false);
+});
+
+test("delete() removes entries and reports whether one existed", async () => {
+ const { SecureCache } = await load();
+ const cache = new SecureCache(60000);
+
+ cache.set("key1", "value1");
+ assert.equal(cache.delete("key1"), true);
+ assert.equal(cache.get("key1"), undefined);
+ assert.equal(cache.delete("nonexistent"), false);
+});
+
+test("clear() empties the cache", async () => {
+ const { SecureCache } = await load();
+ const cache = new SecureCache(60000);
+
+ cache.set("a", "1");
+ cache.set("b", "2");
+ cache.clear();
+ assert.equal(cache.size, 0);
+ assert.equal(cache.get("a"), undefined);
+});
+
+test("size counts expired entries until cleanup() sweeps them", async (t) => {
+ const { SecureCache } = await load();
+ t.mock.timers.enable({ apis: ["Date"] });
+
+ const cache = new SecureCache(1000);
+ cache.set("old", "1");
+
+ t.mock.timers.tick(1001);
+ assert.equal(cache.size, 1);
+
+ cache.set("new", "2");
+ cache.cleanup();
+
+ assert.equal(cache.size, 1);
+ assert.equal(cache.get("old"), undefined);
+ assert.equal(cache.get("new"), "2");
+});
+
+test("startAutoCleanup sweeps on the interval and its stop function halts sweeping", async (t) => {
+ const { SecureCache } = await load();
+ t.mock.timers.enable({ apis: ["Date", "setInterval"] });
+
+ const cache = new SecureCache(500);
+ cache.set("key1", "value1");
+
+ const stop = cache.startAutoCleanup(1000);
+
+ t.mock.timers.tick(600);
+ assert.equal(cache.size, 1, "expired entry stays until the interval fires");
+
+ t.mock.timers.tick(500);
+ assert.equal(cache.size, 0, "interval sweep removes the expired entry");
+
+ cache.set("key2", "value2");
+ stop();
+ t.mock.timers.tick(2000);
+ assert.equal(cache.size, 1, "no sweeps after stop, even for expired entries");
+});
+
+test("setting an existing key overwrites its value", async () => {
+ const { SecureCache } = await load();
+ const cache = new SecureCache(60000);
+
+ cache.set("key1", "first");
+ cache.set("key1", "second");
+ assert.equal(cache.get("key1"), "second");
+});
diff --git a/test/helpers/secureEndpoint.test.js b/test/helpers/secureEndpoint.test.js
new file mode 100644
index 000000000..c9a8a7427
--- /dev/null
+++ b/test/helpers/secureEndpoint.test.js
@@ -0,0 +1,66 @@
+const test = require("node:test");
+const assert = require("node:assert/strict");
+
+// Requires Node's native TypeScript type-stripping (Node >= 22.6 with
+// --experimental-strip-types, on by default in Node 23.6+/24). CI runs Node 24.
+
+const load = () => import("../../src/utils/urlUtils.ts");
+
+test("https endpoints are secure; plain http to a public host is not", async () => {
+ const { isSecureEndpoint } = await load();
+
+ assert.equal(isSecureEndpoint("https://api.openai.com/v1"), true);
+ assert.equal(isSecureEndpoint("http://api.openai.com/v1"), false);
+});
+
+test("loopback hosts are allowed over http", async () => {
+ const { isSecureEndpoint } = await load();
+
+ assert.equal(isSecureEndpoint("http://localhost:8080"), true);
+ assert.equal(isSecureEndpoint("http://127.0.0.1:5000"), true);
+ assert.equal(isSecureEndpoint("http://127.0.1.1:3000"), true);
+ assert.equal(isSecureEndpoint("http://0.0.0.0:8000"), true);
+ assert.equal(isSecureEndpoint("http://[::1]:8080"), true);
+});
+
+test("RFC 1918 private ranges are allowed over http — self-hosted LLM servers live there", async () => {
+ const { isSecureEndpoint } = await load();
+
+ assert.equal(isSecureEndpoint("http://10.0.0.5:8080"), true);
+ assert.equal(isSecureEndpoint("http://192.168.1.100:8080"), true);
+ assert.equal(isSecureEndpoint("http://172.16.0.1:8080"), true);
+ assert.equal(isSecureEndpoint("http://172.31.255.255:8080"), true);
+});
+
+test("172.x outside the 16-31 private block is public and rejected over http", async () => {
+ const { isSecureEndpoint } = await load();
+
+ assert.equal(isSecureEndpoint("http://172.15.0.1:8080"), false);
+ assert.equal(isSecureEndpoint("http://172.32.0.1:8080"), false);
+});
+
+test("CGNAT 100.64.0.0/10 is treated as private (Tailscale addresses)", async () => {
+ const { isSecureEndpoint } = await load();
+
+ assert.equal(isSecureEndpoint("http://100.64.0.1:8080"), true);
+ assert.equal(isSecureEndpoint("http://100.127.255.254:8080"), true);
+ assert.equal(isSecureEndpoint("http://100.63.0.1:8080"), false);
+ assert.equal(isSecureEndpoint("http://100.128.0.1:8080"), false);
+});
+
+test("link-local, IPv6 ULA, and .local hostnames are allowed over http", async () => {
+ const { isSecureEndpoint } = await load();
+
+ assert.equal(isSecureEndpoint("http://169.254.1.1:8080"), true);
+ assert.equal(isSecureEndpoint("http://[fe80::1]:8080"), true);
+ assert.equal(isSecureEndpoint("http://[fc00::1]:8080"), true);
+ assert.equal(isSecureEndpoint("http://[fd12::1]:8080"), true);
+ assert.equal(isSecureEndpoint("http://myserver.local:8080"), true);
+});
+
+test("unparseable input is never secure", async () => {
+ const { isSecureEndpoint } = await load();
+
+ assert.equal(isSecureEndpoint(""), false);
+ assert.equal(isSecureEndpoint("not-a-url"), false);
+});