mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-11-19 11:26:02 +00:00
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:
@@ -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`
|
||||
|
||||
|
||||
@@ -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();
|
||||
|
||||
@@ -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",
|
||||
|
||||
@@ -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")
|
||||
);
|
||||
}
|
||||
|
||||
|
||||
@@ -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);
|
||||
|
||||
@@ -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 {
|
||||
|
||||
@@ -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,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`,
|
||||
);
|
||||
}
|
||||
|
||||
@@ -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. */
|
||||
|
||||
@@ -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;
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user