From ecf0e14387482bf7ca35c7797292d6bbb67b66d1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Miguel=20=C3=81ngel?= Date: Thu, 5 Nov 2026 10:56:35 +0000 Subject: [PATCH] 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 --- docs/packages/cli.mdx | 5 ++- packages/cli/scripts/test-home.mjs | 1 + .../cli/src/commands/previewLifecycle.test.ts | 17 ++++++++++ packages/cli/src/commands/previewLifecycle.ts | 8 ++++- .../src/media-use/lib/local-media-search.mjs | 8 +++-- .../media-use/lib/local-media-search.test.mjs | 23 +++++++++++++ packages/cli/src/registry/localModel.test.ts | 15 ++++++++ packages/cli/src/registry/localModel.ts | 9 ++--- .../cli/src/registry/localSemantic.test.ts | 34 +++++++++++++++++++ packages/cli/src/registry/localSemantic.ts | 5 ++- packages/cli/src/registry/remote.test.ts | 13 +++++++ packages/cli/src/registry/remote.ts | 9 ++--- packages/cli/src/utils/appHistory.test.ts | 12 +++++++ packages/cli/src/utils/appHistory.ts | 5 +-- packages/core/src/cacheDir.test.ts | 10 +++++- packages/core/src/cacheDir.ts | 4 +++ 16 files changed, 162 insertions(+), 16 deletions(-) create mode 100644 packages/cli/src/media-use/lib/local-media-search.test.mjs diff --git a/docs/packages/cli.mdx b/docs/packages/cli.mdx index f770228aad..a56d50f1e0 100644 --- a/docs/packages/cli.mdx +++ b/docs/packages/cli.mdx @@ -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` diff --git a/packages/cli/scripts/test-home.mjs b/packages/cli/scripts/test-home.mjs index 07feafbfc6..7a6a19c8e6 100644 --- a/packages/cli/scripts/test-home.mjs +++ b/packages/cli/scripts/test-home.mjs @@ -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", diff --git a/packages/cli/src/commands/previewLifecycle.test.ts b/packages/cli/src/commands/previewLifecycle.test.ts index 3a0cff16aa..ecf973d713 100644 --- a/packages/cli/src/commands/previewLifecycle.test.ts +++ b/packages/cli/src/commands/previewLifecycle.test.ts @@ -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([]); + }); +}); diff --git a/packages/cli/src/commands/previewLifecycle.ts b/packages/cli/src/commands/previewLifecycle.ts index 32cd1afe37..0f3e380c18 100644 --- a/packages/cli/src/commands/previewLifecycle.ts +++ b/packages/cli/src/commands/previewLifecycle.ts @@ -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 { diff --git a/packages/cli/src/media-use/lib/local-media-search.mjs b/packages/cli/src/media-use/lib/local-media-search.mjs index 3e0d31be22..a910ee00c3 100644 --- a/packages/cli/src/media-use/lib/local-media-search.mjs +++ b/packages/cli/src/media-use/lib/local-media-search.mjs @@ -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 = {}) { diff --git a/packages/cli/src/media-use/lib/local-media-search.test.mjs b/packages/cli/src/media-use/lib/local-media-search.test.mjs new file mode 100644 index 0000000000..c8b68e954b --- /dev/null +++ b/packages/cli/src/media-use/lib/local-media-search.test.mjs @@ -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" }]); +}); diff --git a/packages/cli/src/registry/localModel.test.ts b/packages/cli/src/registry/localModel.test.ts index a4d7e5a3a9..da907e33fd 100644 --- a/packages/cli/src/registry/localModel.test.ts +++ b/packages/cli/src/registry/localModel.test.ts @@ -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(); diff --git a/packages/cli/src/registry/localModel.ts b/packages/cli/src/registry/localModel.ts index 3d28b141f7..b16d85e00f 100644 --- a/packages/cli/src/registry/localModel.ts +++ b/packages/cli/src/registry/localModel.ts @@ -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 { 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(); diff --git a/packages/cli/src/registry/localSemantic.test.ts b/packages/cli/src/registry/localSemantic.test.ts index d775f26e48..f45cb0b2e8 100644 --- a/packages/cli/src/registry/localSemantic.test.ts +++ b/packages/cli/src/registry/localSemantic.test.ts @@ -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", diff --git a/packages/cli/src/registry/localSemantic.ts b/packages/cli/src/registry/localSemantic.ts index b81c81c766..4ab389e014 100644 --- a/packages/cli/src/registry/localSemantic.ts +++ b/packages/cli/src/registry/localSemantic.ts @@ -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") ); } diff --git a/packages/cli/src/registry/remote.test.ts b/packages/cli/src/registry/remote.test.ts index c067bcdd40..90ddce6c98 100644 --- a/packages/cli/src/registry/remote.test.ts +++ b/packages/cli/src/registry/remote.test.ts @@ -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); diff --git a/packages/cli/src/registry/remote.ts b/packages/cli/src/registry/remote.ts index c6731457da..0a2496c160 100644 --- a/packages/cli/src/registry/remote.ts +++ b/packages/cli/src/registry/remote.ts @@ -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 { @@ -49,7 +50,7 @@ interface CacheEntry { 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(entry: CacheEntry): boolean { function writeCache(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 = { fetchedAt: Date.now(), data }; publishRegistryFile(root, basename(path), JSON.stringify(entry)); } catch { diff --git a/packages/cli/src/utils/appHistory.test.ts b/packages/cli/src/utils/appHistory.test.ts index 3bf2f61e48..2087e4eec2 100644 --- a/packages/cli/src/utils/appHistory.test.ts +++ b/packages/cli/src/utils/appHistory.test.ts @@ -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); + }); +}); diff --git a/packages/cli/src/utils/appHistory.ts b/packages/cli/src/utils/appHistory.ts index e9375dcb05..5299ebf7a2 100644 --- a/packages/cli/src/utils/appHistory.ts +++ b/packages/cli/src/utils/appHistory.ts @@ -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`, ); } diff --git a/packages/core/src/cacheDir.test.ts b/packages/core/src/cacheDir.test.ts index 0edded2d1e..b8fbf92308 100644 --- a/packages/core/src/cacheDir.test.ts +++ b/packages/core/src/cacheDir.test.ts @@ -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. */ diff --git a/packages/core/src/cacheDir.ts b/packages/core/src/cacheDir.ts index 6d364613a2..4ebc980497 100644 --- a/packages/core/src/cacheDir.ts +++ b/packages/core/src/cacheDir.ts @@ -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; +}