fix(cli): previews and every per-user cache follow HYPERFRAMES_CACHE_DIR (#7224)

* fix(cli): a preview's session follows HYPERFRAMES_CACHE_DIR when it is set

* docs(cli): background previews follow HYPERFRAMES_CACHE_DIR

* test(cli): unstub the preview test's env in a block body

* test(cli): clear HYPERFRAMES_CACHE_DIR in the CLI's test home

* fix(cli): registry cache, search model, catalog and catch-up follow HYPERFRAMES_CACHE_DIR

* style(cli): format the media search cache test

* test(cli): compare the model path against an absolute cache folder on Windows too

* fix(cli): both catalog readers treat an empty HYPERFRAMES_CATALOG_ARTIFACT_DIR as unset
This commit is contained in:
Miguel Ángel
2026-11-05 10:56:35 +00:00
committed by GitHub
parent 0180c603d1
commit ecf0e14387
16 changed files with 162 additions and 16 deletions
+4 -1
View File
@@ -2007,7 +2007,10 @@ default 3); `--json` prints the results as JSON.
## Keep the environment healthy
HyperFrames keeps what it downloads and builds (the headless browser, models, optional packages, fonts and project
history) under `~/.cache/hyperframes`. Set `HYPERFRAMES_CACHE_DIR` to an absolute path to keep it somewhere else.
history) under `~/.cache/hyperframes`. Set `HYPERFRAMES_CACHE_DIR` to an absolute path to keep it somewhere else;
background preview records, the registry's manifest cache, the local search model and catalog, and the records of
what an app already showed then move there too, so a sandbox that only lets the CLI write inside your project can
run them.
### `doctor`
+1
View File
@@ -19,6 +19,7 @@ for (const name of [
"CLAUDE_CONFIG_DIR",
"HEYGEN_CONFIG_DIR",
"HYPERFRAMES_CONFIG_DIR",
"HYPERFRAMES_CACHE_DIR",
"HYPERFRAMES_CATALOG_ARTIFACT_DIR",
"HYPERFRAMES_MEDIA_HOME",
"HF_HOME",
@@ -1490,3 +1490,20 @@ describe("background preview lifecycle", () => {
expect(existsSync(previewSessionPath(projectDir, stateHome))).toBe(false);
});
});
describe("where a preview's session is kept", () => {
it("is under HYPERFRAMES_CACHE_DIR when it is set, not the state folder", () => {
const cache = tempDir("hf-preview-cache-");
const state = tempDir("hf-preview-state-");
vi.stubEnv("HYPERFRAMES_CACHE_DIR", cache);
vi.stubEnv("XDG_STATE_HOME", state);
vi.stubEnv("LOCALAPPDATA", state);
onTestFinished(() => {
vi.unstubAllEnvs();
});
writePreviewSession({ pid: 4321, port: 3210, projectDir, logPath: "/tmp/preview.log" });
expect(previewSessionPath(projectDir).startsWith(cache)).toBe(true);
expect(existsSync(previewSessionPath(projectDir))).toBe(true);
expect(readdirSync(state)).toEqual([]);
});
});
@@ -20,6 +20,7 @@ import {
scanActiveServers,
type ActiveServer,
} from "../server/portUtils.js";
import { namedCacheDir } from "@hyperframes/core/cache-dir";
import type { BrowserGpuMode } from "../browser/gpuPolicy.js";
import { windowsLocalAppData } from "../utils/windowsAppData.js";
import { isProcessDescendant, processIdentity } from "../utils/orphanCleanup.js";
@@ -88,7 +89,12 @@ interface LifecycleDependencies {
}
function defaultStateHome(): string {
return process.env.XDG_STATE_HOME || windowsLocalAppData() || join(homedir(), ".local", "state");
return (
namedCacheDir("state") ||
process.env.XDG_STATE_HOME ||
windowsLocalAppData() ||
join(homedir(), ".local", "state")
);
}
function normalized(path: string): string {
@@ -1,11 +1,15 @@
import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
import { homedir } from "node:os";
import { join } from "node:path";
import { join, resolve } from "node:path";
const DEFAULT_DIRECTORY = join(homedir(), ".hyperframes", "catalog");
function directory() {
return process.env.HYPERFRAMES_CATALOG_ARTIFACT_DIR || DEFAULT_DIRECTORY;
const cache = process.env.HYPERFRAMES_CACHE_DIR;
return (
process.env.HYPERFRAMES_CATALOG_ARTIFACT_DIR ||
(cache ? join(resolve(cache), "catalog") : DEFAULT_DIRECTORY)
);
}
export async function fetchMediaVectors(registryBaseUrl, options = {}) {
@@ -0,0 +1,23 @@
import { strict as assert } from "node:assert";
import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { test } from "node:test";
import { mediaVectorRows } from "./local-media-search.mjs";
test("media vectors are read from the cache folder's catalog when HYPERFRAMES_CACHE_DIR is set", (t) => {
const cache = mkdtempSync(join(tmpdir(), "hf-cache-"));
const prior = process.env.HYPERFRAMES_CACHE_DIR;
process.env.HYPERFRAMES_CACHE_DIR = cache;
t.after(() => {
if (prior === undefined) delete process.env.HYPERFRAMES_CACHE_DIR;
else process.env.HYPERFRAMES_CACHE_DIR = prior;
rmSync(cache, { recursive: true, force: true });
});
mkdirSync(join(cache, "catalog"));
writeFileSync(
join(cache, "catalog", "media-vectors.json"),
JSON.stringify({ rows: [{ id: "a" }] }),
);
assert.deepEqual(mediaVectorRows(), [{ id: "a" }]);
});
@@ -1,3 +1,5 @@
import { tmpdir } from "node:os";
import { join } from "node:path";
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
const readConfig = vi.fn();
@@ -75,6 +77,19 @@ beforeEach(() => {
afterEach(() => vi.clearAllMocks());
describe("where the model is kept", () => {
it("is under HYPERFRAMES_CACHE_DIR when it is set", () => {
const cache = join(tmpdir(), "hf-cache-elsewhere");
vi.stubEnv("HYPERFRAMES_CACHE_DIR", cache);
try {
expect(localModelPath().startsWith(join(cache, "models"))).toBe(true);
expect(localTokenizerPath().startsWith(join(cache, "models"))).toBe(true);
} finally {
vi.unstubAllEnvs();
}
});
});
describe("consent state", () => {
it("reports never-asked as undefined", () => {
expect(localModelConsent()).toBeUndefined();
+5 -4
View File
@@ -16,6 +16,7 @@
import { createHash } from "node:crypto";
import { existsSync, mkdirSync, readFileSync, unlinkSync } from "node:fs";
import { homedir } from "node:os";
import { namedCacheDir } from "@hyperframes/core/cache-dir";
import { join } from "node:path";
import { downloadFile } from "../utils/download.js";
@@ -34,7 +35,7 @@ export const LOCAL_MODEL_SIZE_MB = 33;
/** bge retrieval expects short queries to carry this prefix; passages do not. */
export const QUERY_INSTRUCTION = "Represent this sentence for searching relevant passages: ";
const MODELS_DIR = join(homedir(), ".hyperframes", "models");
const modelsDir = () => namedCacheDir("models") ?? join(homedir(), ".hyperframes", "models");
/**
* Where the two halves come from.
@@ -97,11 +98,11 @@ export function assumeLocalModelConsent(): LocalModelDecision {
}
export function localModelPath(): string {
return join(MODELS_DIR, `${LOCAL_MODEL_ID}.onnx`);
return join(modelsDir(), `${LOCAL_MODEL_ID}.onnx`);
}
export function localTokenizerPath(): string {
return join(MODELS_DIR, `${LOCAL_MODEL_ID}.tokenizer.json`);
return join(modelsDir(), `${LOCAL_MODEL_ID}.tokenizer.json`);
}
function modelFileIsValid(file: ModelFile): boolean {
@@ -152,7 +153,7 @@ export function localModelStatus(): LocalModelStatus {
export async function ensureLocalModel(): Promise<boolean> {
if (isLocalModelReady()) return true;
try {
mkdirSync(MODELS_DIR, { recursive: true });
mkdirSync(modelsDir(), { recursive: true });
for (const file of LOCAL_MODEL_ARTIFACTS) {
if (modelFileIsValid(file)) continue;
const dest = file.dest();
@@ -6,6 +6,7 @@ import { join } from "node:path";
import {
cachedLocalVectorRevision,
fetchLocalVectors,
hasLocalVectors,
isMediaVectorRow,
mediaSemanticRanking,
vectorPairAgrees,
@@ -201,6 +202,39 @@ describe("fetchLocalVectors", () => {
});
});
describe("where the catalog vectors are read", () => {
it("is the cache folder's catalog when HYPERFRAMES_CACHE_DIR is set", () => {
const cache = mkdtempSync(join(tmpdir(), "hf-cache-"));
vi.stubEnv("HYPERFRAMES_CACHE_DIR", cache);
try {
mkdirSync(join(cache, "catalog"));
writeFileSync(join(cache, "catalog", "local-vectors.json"), "{}");
writeFileSync(join(cache, "catalog", "local-vectors.bin"), "");
expect(hasLocalVectors()).toBe(true);
} finally {
vi.unstubAllEnvs();
rmSync(cache, { recursive: true, force: true });
}
});
});
describe("an empty HYPERFRAMES_CATALOG_ARTIFACT_DIR", () => {
it("counts as unset, as media search reads it", () => {
const cache = mkdtempSync(join(tmpdir(), "hf-cache-"));
vi.stubEnv("HYPERFRAMES_CACHE_DIR", cache);
vi.stubEnv("HYPERFRAMES_CATALOG_ARTIFACT_DIR", "");
try {
mkdirSync(join(cache, "catalog"));
writeFileSync(join(cache, "catalog", "local-vectors.json"), "{}");
writeFileSync(join(cache, "catalog", "local-vectors.bin"), "");
expect(hasLocalVectors()).toBe(true);
} finally {
vi.unstubAllEnvs();
rmSync(cache, { recursive: true, force: true });
}
});
});
describe("media-vector validation", () => {
const row = {
id: "click",
+4 -1
View File
@@ -15,6 +15,7 @@
// Vector metadata validation is intentionally defensive at this file boundary.
import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
import { homedir } from "node:os";
import { namedCacheDir } from "@hyperframes/core/cache-dir";
import { join } from "node:path";
import { cosine, loadLocalEmbedder } from "./localEmbedder.js";
@@ -78,7 +79,9 @@ const CATALOG_ARTIFACT_TIMEOUT_MS = 30_000;
/** Where the bundled vector set lives, overridable for development. */
function localVectorDirectory(): string {
return (
process.env["HYPERFRAMES_CATALOG_ARTIFACT_DIR"] ?? join(homedir(), ".hyperframes", "catalog")
process.env["HYPERFRAMES_CATALOG_ARTIFACT_DIR"] ||
namedCacheDir("catalog") ||
join(homedir(), ".hyperframes", "catalog")
);
}
+13
View File
@@ -92,6 +92,19 @@ describe("readRegistryManifest", () => {
});
describe("fetchRegistryManifest", () => {
it("caches manifests under HYPERFRAMES_CACHE_DIR when it is set", async () => {
const cache = mkdtempSync(join(tmpdir(), "hf-cache-"));
vi.stubEnv("HYPERFRAMES_CACHE_DIR", cache);
try {
vi.spyOn(globalThis, "fetch").mockResolvedValueOnce(ok(MANIFEST));
await fetchRegistryManifest(DEFAULT_REGISTRY_URL);
expect(readdirSync(join(cache, "registry"))).toHaveLength(1);
} finally {
vi.unstubAllEnvs();
rmSync(cache, { recursive: true, force: true });
}
});
it("rejects poisoned stale cache data instead of returning it on network failure", async () => {
vi.spyOn(globalThis, "fetch").mockResolvedValueOnce(ok(MANIFEST));
await fetchRegistryManifest(DEFAULT_REGISTRY_URL);
+5 -4
View File
@@ -21,6 +21,7 @@ import { validRegistryName, validRegistryManifest, validRegistryItem } from "./v
import { join, basename } from "node:path";
import { mkdirSync } from "node:fs";
import { homedir } from "node:os";
import { namedCacheDir } from "@hyperframes/core/cache-dir";
import {
ITEM_TYPE_DIRS,
type FileTarget,
@@ -39,7 +40,7 @@ const MAX_MANIFEST_BYTES = 10 * 1024 * 1024;
// 24h TTL on manifest fetches so the interactive picker stays snappy offline.
// Item files aren't cached — they're written straight to destDir on install.
const CACHE_DIR = join(homedir(), ".hyperframes", "cache");
const cacheDir = () => namedCacheDir("registry") ?? join(homedir(), ".hyperframes", "cache");
const CACHE_TTL_MS = 24 * 60 * 60 * 1000;
interface CacheEntry<T> {
@@ -49,7 +50,7 @@ interface CacheEntry<T> {
function cachePath(baseUrl: string, key: string): string {
const slug = baseUrl.replace(/[^a-zA-Z0-9]/g, "_");
return join(CACHE_DIR, `${slug}__${key}.json`);
return join(cacheDir(), `${slug}__${key}.json`);
}
/**
@@ -90,8 +91,8 @@ function isFresh<T>(entry: CacheEntry<T>): boolean {
function writeCache<T>(path: string, data: T): void {
try {
mkdirSync(CACHE_DIR, { recursive: true });
const root = registryRoot(CACHE_DIR);
mkdirSync(cacheDir(), { recursive: true });
const root = registryRoot(cacheDir());
const entry: CacheEntry<T> = { fetchedAt: Date.now(), data };
publishRegistryFile(root, basename(path), JSON.stringify(entry));
} catch {
+12
View File
@@ -1,4 +1,5 @@
import {
existsSync,
mkdirSync,
mkdtempSync,
readFileSync,
@@ -234,3 +235,14 @@ describe("addCatchUpNote", () => {
addCatchUpNote(mkdtempSync(join(tmpdir(), "hf-note-")));
});
});
describe("app history under HYPERFRAMES_CACHE_DIR", () => {
it("keeps the seen record in the cache folder when it is set", () => {
const cache = mkdtempSync(join(tmpdir(), "hf-cache-"));
vi.stubEnv("HYPERFRAMES_CACHE_DIR", cache);
const dir = mkdtempSync(join(tmpdir(), "hf-project-"));
handedOverAt(dir, "2026-10-01T00:00:00Z");
expect(seenPath(dir).startsWith(join(cache, "catch-up"))).toBe(true);
expect(existsSync(seenPath(dir))).toBe(true);
});
});
+3 -2
View File
@@ -3,6 +3,7 @@ import { lstatSync, mkdirSync, readdirSync } from "node:fs";
import { realpath } from "@hyperframes/core/safe-path";
import { homedir } from "node:os";
import { dirname, join, relative, resolve, sep } from "node:path";
import { namedCacheDir } from "@hyperframes/core/cache-dir";
import { windowsLocalAppData } from "./windowsAppData.js";
import { readPlainFile, readRecord, recordChangedAt, replaceFile } from "./projectRecords.js";
@@ -65,8 +66,8 @@ export function seenPath(dir: string): string {
const key = createHash("sha256").update(real).digest("hex").slice(0, 32);
const base = windowsLocalAppData();
return join(
base ? join(base, "hyperframes") : join(homedir(), ".hyperframes"),
"catch-up",
namedCacheDir("catch-up") ??
join(base ? join(base, "hyperframes") : join(homedir(), ".hyperframes"), "catch-up"),
`${key}.json`,
);
}
+9 -1
View File
@@ -2,7 +2,7 @@ import { readdirSync, readFileSync } from "node:fs";
import { homedir, tmpdir } from "node:os";
import { join, resolve } from "node:path";
import { afterEach, describe, expect, it, vi } from "vitest";
import { hyperframesCacheDir } from "./cacheDir.js";
import { hyperframesCacheDir, namedCacheDir } from "./cacheDir.js";
afterEach(() => vi.unstubAllEnvs());
@@ -20,6 +20,14 @@ describe("hyperframesCacheDir", () => {
vi.stubEnv("HYPERFRAMES_CACHE_DIR", "rel/cache");
expect(hyperframesCacheDir("tts")).toBe(join(resolve("rel/cache"), "tts"));
});
it("names a folder in the cache only when HYPERFRAMES_CACHE_DIR is set", () => {
vi.stubEnv("HYPERFRAMES_CACHE_DIR", "");
expect(namedCacheDir("state")).toBeUndefined();
const elsewhere = join(tmpdir(), "elsewhere-cache");
vi.stubEnv("HYPERFRAMES_CACHE_DIR", elsewhere);
expect(namedCacheDir("state")).toBe(join(elsewhere, "state"));
});
});
/** Source files under every package's src, tests and test helpers left out. */
+4
View File
@@ -5,3 +5,7 @@ export function hyperframesCacheDir(...parts: string[]): string {
const named = process.env["HYPERFRAMES_CACHE_DIR"];
return join(named ? resolve(named) : join(homedir(), ".cache", "hyperframes"), ...parts);
}
export function namedCacheDir(...parts: string[]): string | undefined {
return process.env["HYPERFRAMES_CACHE_DIR"] ? hyperframesCacheDir(...parts) : undefined;
}