Skip to content

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

fix(models): Honor redirected cache roots (#1721)

Chad Pihada39195afaf4
diff --git a/src/helpers/modelDirUtils.js b/src/helpers/modelDirUtils.js
index 416b244bc..98724f94b 100644
--- a/src/helpers/modelDirUtils.js
+++ b/src/helpers/modelDirUtils.js
@@ -14,30 +14,42 @@ function ensureDir(dir) {
return dir;
}
-function getAsciiSafeCacheRoot() {
- const envOverride =
- process.env.OPENWHISPR_CACHE_ROOT ||
- (process.env.XDG_CACHE_HOME ? path.join(process.env.XDG_CACHE_HOME, "openwhispr") : null);
- if (envOverride && !pathHasProblematicChars(envOverride)) {
+function getAsciiSafeFallbackRoot() {
+ const candidates = [
+ path.join(process.env.ProgramData || "C:\\ProgramData", "OpenWhispr", "cache"),
+ path.join(process.env.SystemDrive || "C:", "OpenWhispr", "cache"),
+ ];
+
+ for (const candidate of candidates) {
+ if (pathHasProblematicChars(candidate)) continue;
try {
- return ensureDir(envOverride);
- } catch {
- // fall through
+ return ensureDir(candidate);
+ } catch {}
+ }
+
+ return null;
+}
+
+function getPreferredCacheRoot(homeCache) {
+ if (process.env.OPENWHISPR_CACHE_ROOT) {
+ return process.env.OPENWHISPR_CACHE_ROOT;
+ }
+
+ if (process.platform === "win32") {
+ const redirectedProfile = process.env.USERPROFILE;
+ if (redirectedProfile && path.isAbsolute(redirectedProfile)) {
+ return path.join(redirectedProfile, ".cache", "openwhispr");
}
}
- const fallbackBase = process.env.ProgramData || "C:\\ProgramData";
- const fallback = path.join(fallbackBase, "OpenWhispr", "cache");
- try {
- return ensureDir(fallback);
- } catch {
- const rootFallback = path.join(process.env.SystemDrive || "C:", "OpenWhispr", "cache");
- try {
- return ensureDir(rootFallback);
- } catch {
- return null;
+ if (process.platform === "linux") {
+ const xdgCacheHome = process.env.XDG_CACHE_HOME;
+ if (xdgCacheHome && path.isAbsolute(xdgCacheHome)) {
+ return path.join(xdgCacheHome, "openwhispr");
}
}
+
+ return homeCache;
}
// Only these subdirs resolve through getCacheRoot(). qdrant-data,
@@ -45,45 +57,80 @@ function getAsciiSafeCacheRoot() {
// managers (and tolerate non-ASCII paths), so they must stay put.
const RELOCATED_SUBDIRS = ["whisper-models", "parakeet-models", "diarization-models", "models"];
-let migratedLegacyRoot = null;
+let migratedRootPair = null;
-function migrateLegacyModelDirs(legacyRoot, safeRoot) {
- if (migratedLegacyRoot === legacyRoot) return;
- migratedLegacyRoot = legacyRoot;
- for (const subdir of RELOCATED_SUBDIRS) {
- const from = path.join(legacyRoot, subdir);
- const to = path.join(safeRoot, subdir);
+function rollbackMigration(completedMoves) {
+ for (const move of completedMoves.reverse()) {
try {
+ if (!fs.existsSync(move.to)) continue;
+
+ if (move.copied) {
+ fs.cpSync(move.to, move.from, { recursive: true });
+ fs.rmSync(move.to, { recursive: true, force: true });
+ } else if (!fs.existsSync(move.from)) {
+ fs.renameSync(move.to, move.from);
+ }
+ } catch {}
+ }
+}
+
+function migrateLegacyModelDirs(legacyRoot, targetRoot) {
+ const rootPair = `${legacyRoot}\0${targetRoot}`;
+ if (migratedRootPair === rootPair) return true;
+
+ const completedMoves = [];
+ let staging = null;
+ try {
+ ensureDir(targetRoot);
+
+ for (const subdir of RELOCATED_SUBDIRS) {
+ const from = path.join(legacyRoot, subdir);
+ const to = path.join(targetRoot, subdir);
if (!fs.existsSync(from) || fs.existsSync(to)) continue;
+
try {
fs.renameSync(from, to);
+ completedMoves.push({ from, to, copied: false });
} catch {
// Cross-volume move: copy to a staging dir first so an interrupted
// copy can never be mistaken for a complete model dir.
- const staging = `${to}.migrating`;
+ staging = `${to}.migrating`;
fs.rmSync(staging, { recursive: true, force: true });
fs.cpSync(from, staging, { recursive: true });
fs.renameSync(staging, to);
- fs.rmSync(from, { recursive: true, force: true });
+ staging = null;
+ completedMoves.push({ from, to, copied: true });
}
- } catch {
- // Leave the legacy copy in place; the model re-downloads if needed.
}
+
+ for (const move of completedMoves) {
+ if (move.copied) fs.rmSync(move.from, { recursive: true, force: true });
+ }
+
+ migratedRootPair = rootPair;
+ return true;
+ } catch {
+ if (staging) {
+ try {
+ fs.rmSync(staging, { recursive: true, force: true });
+ } catch {}
+ }
+ rollbackMigration(completedMoves);
+ return false;
}
}
function getCacheRoot() {
const homeDir = app?.getPath?.("home") || os.homedir();
const homeCache = path.join(homeDir, ".cache", "openwhispr");
+ let targetRoot = getPreferredCacheRoot(homeCache);
- if (process.platform !== "win32" || !pathHasProblematicChars(homeCache)) {
- return homeCache;
+ if (process.platform === "win32" && pathHasProblematicChars(targetRoot)) {
+ targetRoot = getAsciiSafeFallbackRoot() || homeCache;
}
- const safeRoot = getAsciiSafeCacheRoot();
- if (!safeRoot) return homeCache;
- migrateLegacyModelDirs(homeCache, safeRoot);
- return safeRoot;
+ if (targetRoot === homeCache) return homeCache;
+ return migrateLegacyModelDirs(homeCache, targetRoot) ? targetRoot : homeCache;
}
function getModelsDirForService(service) {
diff --git a/test/helpers/modelDirUtils.test.js b/test/helpers/modelDirUtils.test.js
index 044ce27ad..2dbb6fd45 100644
--- a/test/helpers/modelDirUtils.test.js
+++ b/test/helpers/modelDirUtils.test.js
@@ -5,7 +5,7 @@ const path = require("path");
const Module = require("node:module");
const { describe, it, beforeEach, afterEach } = require("node:test");
-describe("modelDirUtils ASCII-safe cache (#1399)", () => {
+describe("modelDirUtils cache policy (#1279, #1399)", () => {
const originalPlatform = Object.getOwnPropertyDescriptor(process, "platform");
const originalEnv = { ...process.env };
const originalLoad = Module._load;
@@ -30,10 +30,44 @@ describe("modelDirUtils ASCII-safe cache (#1399)", () => {
return require("../../src/helpers/modelDirUtils");
}
+ function setPlatform(platform) {
+ Object.defineProperty(process, "platform", { value: platform });
+ }
+
+ function createRedirectedWindowsFixture() {
+ setPlatform("win32");
+ const home = path.join(tempRoot, "Users", "stan");
+ const legacyRoot = path.join(home, ".cache", "openwhispr");
+ const redirectedProfile = path.join(tempRoot, "RedirectedUsers", "stan");
+ const redirectedRoot = path.join(redirectedProfile, ".cache", "openwhispr");
+ process.env.USERPROFILE = redirectedProfile;
+ return { home, legacyRoot, redirectedRoot };
+ }
+
+ function writeModel(directory, name, contents) {
+ fs.mkdirSync(directory, { recursive: true });
+ const filePath = path.join(directory, name);
+ fs.writeFileSync(filePath, contents);
+ return filePath;
+ }
+
+ function withFsOverrides(overrides, callback) {
+ const originals = Object.fromEntries(
+ Object.keys(overrides).map((method) => [method, fs[method]])
+ );
+ Object.assign(fs, overrides);
+ try {
+ return callback();
+ } finally {
+ Object.assign(fs, originals);
+ }
+ }
+
beforeEach(() => {
tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), "ow-cache-test-"));
process.env = { ...originalEnv };
delete process.env.OPENWHISPR_CACHE_ROOT;
+ delete process.env.USERPROFILE;
delete process.env.XDG_CACHE_HOME;
});
@@ -55,7 +89,7 @@ describe("modelDirUtils ASCII-safe cache (#1399)", () => {
});
it("honors OPENWHISPR_CACHE_ROOT when ASCII-safe", () => {
- Object.defineProperty(process, "platform", { value: "win32" });
+ setPlatform("win32");
const override = path.join(tempRoot, "ascii-cache");
process.env.OPENWHISPR_CACHE_ROOT = override;
const { getCacheRoot } = loadFresh(path.join(tempRoot, "使用者", "詩涵"));
@@ -63,8 +97,123 @@ describe("modelDirUtils ASCII-safe cache (#1399)", () => {
assert.ok(fs.existsSync(override));
});
+ it("gives OPENWHISPR_CACHE_ROOT precedence over an ASCII-safe Windows home", () => {
+ setPlatform("win32");
+ const home = path.join(tempRoot, "Users", "stan");
+ const override = path.join(tempRoot, "custom-cache");
+ process.env.OPENWHISPR_CACHE_ROOT = override;
+
+ const { getCacheRoot } = loadFresh(home);
+
+ assert.strictEqual(getCacheRoot(), override);
+ });
+
+ it("uses a redirected USERPROFILE on Windows", () => {
+ const { home, redirectedRoot } = createRedirectedWindowsFixture();
+
+ const { getCacheRoot } = loadFresh(home);
+
+ assert.strictEqual(getCacheRoot(), redirectedRoot);
+ });
+
+ it("honors an absolute XDG_CACHE_HOME on Linux", () => {
+ setPlatform("linux");
+ const home = path.join(tempRoot, "home", "stan");
+ const xdgCacheHome = path.join(tempRoot, "xdg-cache");
+ process.env.XDG_CACHE_HOME = xdgCacheHome;
+
+ const { getCacheRoot } = loadFresh(home);
+
+ assert.strictEqual(getCacheRoot(), path.join(xdgCacheHome, "openwhispr"));
+ });
+
+ it("gives OPENWHISPR_CACHE_ROOT precedence over XDG_CACHE_HOME", () => {
+ setPlatform("linux");
+ const home = path.join(tempRoot, "home", "stan");
+ const override = path.join(tempRoot, "custom-cache");
+ process.env.OPENWHISPR_CACHE_ROOT = override;
+ process.env.XDG_CACHE_HOME = path.join(tempRoot, "xdg-cache");
+
+ const { getCacheRoot } = loadFresh(home);
+
+ assert.strictEqual(getCacheRoot(), override);
+ });
+
+ it("keeps the home cache when XDG_CACHE_HOME is relative", () => {
+ setPlatform("linux");
+ const home = path.join(tempRoot, "home", "stan");
+ process.env.XDG_CACHE_HOME = "relative-cache";
+
+ const { getCacheRoot } = loadFresh(home);
+
+ assert.strictEqual(getCacheRoot(), path.join(home, ".cache", "openwhispr"));
+ });
+
+ it("preserves the macOS home-cache default", () => {
+ setPlatform("darwin");
+ const home = path.join(tempRoot, "Users", "stan");
+
+ const { getCacheRoot } = loadFresh(home);
+
+ assert.strictEqual(getCacheRoot(), path.join(home, ".cache", "openwhispr"));
+ });
+
+ it("honors OPENWHISPR_CACHE_ROOT on macOS", () => {
+ setPlatform("darwin");
+ const home = path.join(tempRoot, "Users", "stan");
+ const override = path.join(tempRoot, "custom-cache");
+ process.env.OPENWHISPR_CACHE_ROOT = override;
+
+ const { getCacheRoot } = loadFresh(home);
+
+ assert.strictEqual(getCacheRoot(), override);
+ });
+
+ it("falls back to ProgramData when redirected USERPROFILE is unsafe", () => {
+ setPlatform("win32");
+ const home = path.join(tempRoot, "Users", "stan");
+ const programData = path.join(tempRoot, "ProgramData");
+ process.env.USERPROFILE = path.join(tempRoot, "Redirected Users", "stan");
+ process.env.ProgramData = programData;
+
+ const { getCacheRoot } = loadFresh(home);
+
+ assert.strictEqual(getCacheRoot(), path.join(programData, "OpenWhispr", "cache"));
+ });
+
+ it("skips an unsafe ProgramData fallback", () => {
+ setPlatform("win32");
+ const home = path.join(tempRoot, "Users", "stan");
+ const systemDrive = path.join(tempRoot, "SystemDrive");
+ process.env.USERPROFILE = path.join(tempRoot, "Redirected Users", "stan");
+ process.env.ProgramData = path.join(tempRoot, "Program Data");
+ process.env.SystemDrive = systemDrive;
+
+ const { getCacheRoot } = loadFresh(home);
+
+ assert.strictEqual(getCacheRoot(), path.join(systemDrive, "OpenWhispr", "cache"));
+ });
+
+ it("keeps all model consumers on the selected cache root", () => {
+ setPlatform("win32");
+ const home = path.join(tempRoot, "Users", "stan");
+ const override = path.join(tempRoot, "custom-cache");
+ process.env.OPENWHISPR_CACHE_ROOT = override;
+
+ const { getCacheRoot, getModelsDirForService } = loadFresh(home);
+
+ assert.strictEqual(getCacheRoot(), override);
+ assert.strictEqual(getModelsDirForService("whisper"), path.join(override, "whisper-models"));
+ assert.strictEqual(getModelsDirForService("parakeet"), path.join(override, "parakeet-models"));
+ assert.strictEqual(
+ getModelsDirForService("diarization"),
+ path.join(override, "diarization-models")
+ );
+ assert.strictEqual(path.join(getCacheRoot(), "models"), path.join(override, "models"));
+ });
+
it("falls back to ProgramData cache when home cache path is non-ASCII", () => {
- Object.defineProperty(process, "platform", { value: "win32" });
+ setPlatform("win32");
const programData = path.join(tempRoot, "ProgramData");
process.env.ProgramData = programData;
@@ -74,21 +223,18 @@ describe("modelDirUtils ASCII-safe cache (#1399)", () => {
const root = getCacheRoot();
assert.strictEqual(root, path.join(programData, "OpenWhispr", "cache"));
assert.ok(fs.existsSync(root));
- assert.strictEqual(
- getModelsDirForService("whisper"),
- path.join(root, "whisper-models")
- );
+ assert.strictEqual(getModelsDirForService("whisper"), path.join(root, "whisper-models"));
});
it("keeps home cache on Windows when the path is ASCII-safe", () => {
- Object.defineProperty(process, "platform", { value: "win32" });
+ setPlatform("win32");
const home = path.join(tempRoot, "Users", "stan");
const { getCacheRoot } = loadFresh(home);
assert.strictEqual(getCacheRoot(), path.join(home, ".cache", "openwhispr"));
});
it("migrates legacy model dirs into the safe root and leaves home-based dirs alone", () => {
- Object.defineProperty(process, "platform", { value: "win32" });
+ setPlatform("win32");
const programData = path.join(tempRoot, "ProgramData");
process.env.ProgramData = programData;
@@ -117,8 +263,161 @@ describe("modelDirUtils ASCII-safe cache (#1399)", () => {
assert.ok(fs.existsSync(path.join(legacyRoot, "embedding-models")));
});
+ it("migrates legacy model dirs when USERPROFILE redirects the cache", () => {
+ const { home, legacyRoot, redirectedRoot } = createRedirectedWindowsFixture();
+ writeModel(path.join(legacyRoot, "whisper-models"), "ggml-base.bin", "model");
+
+ const { getCacheRoot } = loadFresh(home);
+
+ assert.strictEqual(getCacheRoot(), redirectedRoot);
+ assert.strictEqual(
+ fs.readFileSync(path.join(redirectedRoot, "whisper-models", "ggml-base.bin"), "utf8"),
+ "model"
+ );
+ assert.ok(!fs.existsSync(path.join(legacyRoot, "whisper-models")));
+ });
+
+ it("stages cross-volume migrations before removing the legacy model directory", () => {
+ const { home, legacyRoot, redirectedRoot } = createRedirectedWindowsFixture();
+ const legacyModels = path.join(legacyRoot, "whisper-models");
+ const redirectedModels = path.join(redirectedRoot, "whisper-models");
+ writeModel(legacyModels, "ggml-base.bin", "model");
+
+ const { getCacheRoot } = loadFresh(home);
+ const originalRenameSync = fs.renameSync;
+ const root = withFsOverrides(
+ {
+ renameSync: (from, to) => {
+ if (from === legacyModels && to === redirectedModels) {
+ const error = new Error("cross-volume move");
+ error.code = "EXDEV";
+ throw error;
+ }
+ return originalRenameSync(from, to);
+ },
+ },
+ () => getCacheRoot()
+ );
+
+ assert.strictEqual(root, redirectedRoot);
+ assert.ok(fs.existsSync(path.join(redirectedModels, "ggml-base.bin")));
+ assert.ok(!fs.existsSync(legacyModels));
+ assert.ok(!fs.existsSync(`${redirectedModels}.migrating`));
+ });
+
+ it("keeps the legacy cache discoverable after a migration failure and retries later", () => {
+ const { home, legacyRoot, redirectedRoot } = createRedirectedWindowsFixture();
+ const legacyModels = path.join(legacyRoot, "whisper-models");
+ const redirectedModels = path.join(redirectedRoot, "whisper-models");
+ writeModel(legacyModels, "ggml-base.bin", "model");
+
+ const { getCacheRoot } = loadFresh(home);
+ const originalRenameSync = fs.renameSync;
+ const originalCpSync = fs.cpSync;
+ const firstResolution = withFsOverrides(
+ {
+ renameSync: (from, to) => {
+ if (from === legacyModels && to === redirectedModels) {
+ const error = new Error("cross-volume move blocked");
+ error.code = "EXDEV";
+ throw error;
+ }
+ return originalRenameSync(from, to);
+ },
+ cpSync: (from, to, options) => {
+ if (from === legacyModels) throw new Error("copy blocked");
+ return originalCpSync(from, to, options);
+ },
+ },
+ () => getCacheRoot()
+ );
+
+ assert.strictEqual(firstResolution, legacyRoot);
+ assert.ok(fs.existsSync(path.join(legacyModels, "ggml-base.bin")));
+ assert.ok(!fs.existsSync(`${redirectedModels}.migrating`));
+
+ assert.strictEqual(getCacheRoot(), redirectedRoot);
+ assert.ok(fs.existsSync(path.join(redirectedModels, "ggml-base.bin")));
+ assert.ok(!fs.existsSync(legacyModels));
+ });
+
+ it("rolls back earlier moves when staging cleanup fails", () => {
+ const { home, legacyRoot, redirectedRoot } = createRedirectedWindowsFixture();
+ const legacyWhisper = path.join(legacyRoot, "whisper-models");
+ const legacyParakeet = path.join(legacyRoot, "parakeet-models");
+ const redirectedWhisper = path.join(redirectedRoot, "whisper-models");
+ const redirectedParakeet = path.join(redirectedRoot, "parakeet-models");
+ const parakeetStaging = `${redirectedParakeet}.migrating`;
+ writeModel(legacyWhisper, "ggml-base.bin", "whisper");
+ writeModel(legacyParakeet, "model.int8.onnx", "parakeet");
+
+ const { getCacheRoot } = loadFresh(home);
+ const originalRenameSync = fs.renameSync;
+ const originalRmSync = fs.rmSync;
+ const root = withFsOverrides(
+ {
+ renameSync: (from, to) => {
+ if (from === legacyParakeet && to === redirectedParakeet) {
+ const error = new Error("cross-volume move");
+ error.code = "EXDEV";
+ throw error;
+ }
+ return originalRenameSync(from, to);
+ },
+ rmSync: (target, options) => {
+ if (target === parakeetStaging) throw new Error("staging cleanup blocked");
+ return originalRmSync(target, options);
+ },
+ },
+ () => getCacheRoot()
+ );
+
+ assert.strictEqual(root, legacyRoot);
+ assert.ok(fs.existsSync(path.join(legacyWhisper, "ggml-base.bin")));
+ assert.ok(fs.existsSync(path.join(legacyParakeet, "model.int8.onnx")));
+ assert.ok(!fs.existsSync(redirectedWhisper));
+ assert.ok(!fs.existsSync(redirectedParakeet));
+ });
+
+ it("restores files removed by a partial cross-volume source cleanup", () => {
+ const { home, legacyRoot, redirectedRoot } = createRedirectedWindowsFixture();
+ const legacyModels = path.join(legacyRoot, "whisper-models");
+ const redirectedModels = path.join(redirectedRoot, "whisper-models");
+ const firstModel = writeModel(legacyModels, "ggml-base.bin", "base");
+ const secondModel = writeModel(legacyModels, "ggml-small.bin", "small");
+
+ const { getCacheRoot } = loadFresh(home);
+ const originalRenameSync = fs.renameSync;
+ const originalRmSync = fs.rmSync;
+ const root = withFsOverrides(
+ {
+ renameSync: (from, to) => {
+ if (from === legacyModels && to === redirectedModels) {
+ const error = new Error("cross-volume move");
+ error.code = "EXDEV";
+ throw error;
+ }
+ return originalRenameSync(from, to);
+ },
+ rmSync: (target, options) => {
+ if (target === legacyModels) {
+ fs.unlinkSync(firstModel);
+ throw new Error("source cleanup interrupted");
+ }
+ return originalRmSync(target, options);
+ },
+ },
+ () => getCacheRoot()
+ );
+
+ assert.strictEqual(root, legacyRoot);
+ assert.strictEqual(fs.readFileSync(firstModel, "utf8"), "base");
+ assert.strictEqual(fs.readFileSync(secondModel, "utf8"), "small");
+ assert.ok(!fs.existsSync(redirectedModels));
+ });
+
it("never overwrites models already present at the safe root", () => {
- Object.defineProperty(process, "platform", { value: "win32" });
+ setPlatform("win32");
const programData = path.join(tempRoot, "ProgramData");
process.env.ProgramData = programData;