Skip to content

Commit ecf0e14

Browse files
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
1 parent 0180c60 commit ecf0e14

16 files changed

Lines changed: 162 additions & 16 deletions

‎docs/packages/cli.mdx‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2007,7 +2007,10 @@ default 3); `--json` prints the results as JSON.
20072007
## Keep the environment healthy
20082008

20092009
HyperFrames keeps what it downloads and builds (the headless browser, models, optional packages, fonts and project
2010-
history) under `~/.cache/hyperframes`. Set `HYPERFRAMES_CACHE_DIR` to an absolute path to keep it somewhere else.
2010+
history) under `~/.cache/hyperframes`. Set `HYPERFRAMES_CACHE_DIR` to an absolute path to keep it somewhere else;
2011+
background preview records, the registry's manifest cache, the local search model and catalog, and the records of
2012+
what an app already showed then move there too, so a sandbox that only lets the CLI write inside your project can
2013+
run them.
20112014

20122015
### `doctor`
20132016

‎packages/cli/scripts/test-home.mjs‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@ for (const name of [
1919
"CLAUDE_CONFIG_DIR",
2020
"HEYGEN_CONFIG_DIR",
2121
"HYPERFRAMES_CONFIG_DIR",
22+
"HYPERFRAMES_CACHE_DIR",
2223
"HYPERFRAMES_CATALOG_ARTIFACT_DIR",
2324
"HYPERFRAMES_MEDIA_HOME",
2425
"HF_HOME",

‎packages/cli/src/commands/previewLifecycle.test.ts‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1490,3 +1490,20 @@ describe("background preview lifecycle", () => {
14901490
expect(existsSync(previewSessionPath(projectDir, stateHome))).toBe(false);
14911491
});
14921492
});
1493+
1494+
describe("where a preview's session is kept", () => {
1495+
it("is under HYPERFRAMES_CACHE_DIR when it is set, not the state folder", () => {
1496+
const cache = tempDir("hf-preview-cache-");
1497+
const state = tempDir("hf-preview-state-");
1498+
vi.stubEnv("HYPERFRAMES_CACHE_DIR", cache);
1499+
vi.stubEnv("XDG_STATE_HOME", state);
1500+
vi.stubEnv("LOCALAPPDATA", state);
1501+
onTestFinished(() => {
1502+
vi.unstubAllEnvs();
1503+
});
1504+
writePreviewSession({ pid: 4321, port: 3210, projectDir, logPath: "/tmp/preview.log" });
1505+
expect(previewSessionPath(projectDir).startsWith(cache)).toBe(true);
1506+
expect(existsSync(previewSessionPath(projectDir))).toBe(true);
1507+
expect(readdirSync(state)).toEqual([]);
1508+
});
1509+
});

‎packages/cli/src/commands/previewLifecycle.ts‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,7 @@ import {
2020
scanActiveServers,
2121
type ActiveServer,
2222
} from "../server/portUtils.js";
23+
import { namedCacheDir } from "@hyperframes/core/cache-dir";
2324
import type { BrowserGpuMode } from "../browser/gpuPolicy.js";
2425
import { windowsLocalAppData } from "../utils/windowsAppData.js";
2526
import { isProcessDescendant, processIdentity } from "../utils/orphanCleanup.js";
@@ -88,7 +89,12 @@ interface LifecycleDependencies {
8889
}
8990

9091
function defaultStateHome(): string {
91-
return process.env.XDG_STATE_HOME || windowsLocalAppData() || join(homedir(), ".local", "state");
92+
return (
93+
namedCacheDir("state") ||
94+
process.env.XDG_STATE_HOME ||
95+
windowsLocalAppData() ||
96+
join(homedir(), ".local", "state")
97+
);
9298
}
9399

94100
function normalized(path: string): string {

‎packages/cli/src/media-use/lib/local-media-search.mjs‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,15 @@
11
import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
22
import { homedir } from "node:os";
3-
import { join } from "node:path";
3+
import { join, resolve } from "node:path";
44

55
const DEFAULT_DIRECTORY = join(homedir(), ".hyperframes", "catalog");
66

77
function directory() {
8-
return process.env.HYPERFRAMES_CATALOG_ARTIFACT_DIR || DEFAULT_DIRECTORY;
8+
const cache = process.env.HYPERFRAMES_CACHE_DIR;
9+
return (
10+
process.env.HYPERFRAMES_CATALOG_ARTIFACT_DIR ||
11+
(cache ? join(resolve(cache), "catalog") : DEFAULT_DIRECTORY)
12+
);
913
}
1014

1115
export async function fetchMediaVectors(registryBaseUrl, options = {}) {
Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
import { strict as assert } from "node:assert";
2+
import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
3+
import { tmpdir } from "node:os";
4+
import { join } from "node:path";
5+
import { test } from "node:test";
6+
import { mediaVectorRows } from "./local-media-search.mjs";
7+
8+
test("media vectors are read from the cache folder's catalog when HYPERFRAMES_CACHE_DIR is set", (t) => {
9+
const cache = mkdtempSync(join(tmpdir(), "hf-cache-"));
10+
const prior = process.env.HYPERFRAMES_CACHE_DIR;
11+
process.env.HYPERFRAMES_CACHE_DIR = cache;
12+
t.after(() => {
13+
if (prior === undefined) delete process.env.HYPERFRAMES_CACHE_DIR;
14+
else process.env.HYPERFRAMES_CACHE_DIR = prior;
15+
rmSync(cache, { recursive: true, force: true });
16+
});
17+
mkdirSync(join(cache, "catalog"));
18+
writeFileSync(
19+
join(cache, "catalog", "media-vectors.json"),
20+
JSON.stringify({ rows: [{ id: "a" }] }),
21+
);
22+
assert.deepEqual(mediaVectorRows(), [{ id: "a" }]);
23+
});

‎packages/cli/src/registry/localModel.test.ts‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
import { tmpdir } from "node:os";
2+
import { join } from "node:path";
13
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
24

35
const readConfig = vi.fn();
@@ -75,6 +77,19 @@ beforeEach(() => {
7577

7678
afterEach(() => vi.clearAllMocks());
7779

80+
describe("where the model is kept", () => {
81+
it("is under HYPERFRAMES_CACHE_DIR when it is set", () => {
82+
const cache = join(tmpdir(), "hf-cache-elsewhere");
83+
vi.stubEnv("HYPERFRAMES_CACHE_DIR", cache);
84+
try {
85+
expect(localModelPath().startsWith(join(cache, "models"))).toBe(true);
86+
expect(localTokenizerPath().startsWith(join(cache, "models"))).toBe(true);
87+
} finally {
88+
vi.unstubAllEnvs();
89+
}
90+
});
91+
});
92+
7893
describe("consent state", () => {
7994
it("reports never-asked as undefined", () => {
8095
expect(localModelConsent()).toBeUndefined();

‎packages/cli/src/registry/localModel.ts‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@
1616
import { createHash } from "node:crypto";
1717
import { existsSync, mkdirSync, readFileSync, unlinkSync } from "node:fs";
1818
import { homedir } from "node:os";
19+
import { namedCacheDir } from "@hyperframes/core/cache-dir";
1920
import { join } from "node:path";
2021

2122
import { downloadFile } from "../utils/download.js";
@@ -34,7 +35,7 @@ export const LOCAL_MODEL_SIZE_MB = 33;
3435
/** bge retrieval expects short queries to carry this prefix; passages do not. */
3536
export const QUERY_INSTRUCTION = "Represent this sentence for searching relevant passages: ";
3637

37-
const MODELS_DIR = join(homedir(), ".hyperframes", "models");
38+
const modelsDir = () => namedCacheDir("models") ?? join(homedir(), ".hyperframes", "models");
3839

3940
/**
4041
* Where the two halves come from.
@@ -97,11 +98,11 @@ export function assumeLocalModelConsent(): LocalModelDecision {
9798
}
9899

99100
export function localModelPath(): string {
100-
return join(MODELS_DIR, `${LOCAL_MODEL_ID}.onnx`);
101+
return join(modelsDir(), `${LOCAL_MODEL_ID}.onnx`);
101102
}
102103

103104
export function localTokenizerPath(): string {
104-
return join(MODELS_DIR, `${LOCAL_MODEL_ID}.tokenizer.json`);
105+
return join(modelsDir(), `${LOCAL_MODEL_ID}.tokenizer.json`);
105106
}
106107

107108
function modelFileIsValid(file: ModelFile): boolean {
@@ -152,7 +153,7 @@ export function localModelStatus(): LocalModelStatus {
152153
export async function ensureLocalModel(): Promise<boolean> {
153154
if (isLocalModelReady()) return true;
154155
try {
155-
mkdirSync(MODELS_DIR, { recursive: true });
156+
mkdirSync(modelsDir(), { recursive: true });
156157
for (const file of LOCAL_MODEL_ARTIFACTS) {
157158
if (modelFileIsValid(file)) continue;
158159
const dest = file.dest();

‎packages/cli/src/registry/localSemantic.test.ts‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@ import { join } from "node:path";
66
import {
77
cachedLocalVectorRevision,
88
fetchLocalVectors,
9+
hasLocalVectors,
910
isMediaVectorRow,
1011
mediaSemanticRanking,
1112
vectorPairAgrees,
@@ -201,6 +202,39 @@ describe("fetchLocalVectors", () => {
201202
});
202203
});
203204

205+
describe("where the catalog vectors are read", () => {
206+
it("is the cache folder's catalog when HYPERFRAMES_CACHE_DIR is set", () => {
207+
const cache = mkdtempSync(join(tmpdir(), "hf-cache-"));
208+
vi.stubEnv("HYPERFRAMES_CACHE_DIR", cache);
209+
try {
210+
mkdirSync(join(cache, "catalog"));
211+
writeFileSync(join(cache, "catalog", "local-vectors.json"), "{}");
212+
writeFileSync(join(cache, "catalog", "local-vectors.bin"), "");
213+
expect(hasLocalVectors()).toBe(true);
214+
} finally {
215+
vi.unstubAllEnvs();
216+
rmSync(cache, { recursive: true, force: true });
217+
}
218+
});
219+
});
220+
221+
describe("an empty HYPERFRAMES_CATALOG_ARTIFACT_DIR", () => {
222+
it("counts as unset, as media search reads it", () => {
223+
const cache = mkdtempSync(join(tmpdir(), "hf-cache-"));
224+
vi.stubEnv("HYPERFRAMES_CACHE_DIR", cache);
225+
vi.stubEnv("HYPERFRAMES_CATALOG_ARTIFACT_DIR", "");
226+
try {
227+
mkdirSync(join(cache, "catalog"));
228+
writeFileSync(join(cache, "catalog", "local-vectors.json"), "{}");
229+
writeFileSync(join(cache, "catalog", "local-vectors.bin"), "");
230+
expect(hasLocalVectors()).toBe(true);
231+
} finally {
232+
vi.unstubAllEnvs();
233+
rmSync(cache, { recursive: true, force: true });
234+
}
235+
});
236+
});
237+
204238
describe("media-vector validation", () => {
205239
const row = {
206240
id: "click",

‎packages/cli/src/registry/localSemantic.ts‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,7 @@
1515
// Vector metadata validation is intentionally defensive at this file boundary.
1616
import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
1717
import { homedir } from "node:os";
18+
import { namedCacheDir } from "@hyperframes/core/cache-dir";
1819
import { join } from "node:path";
1920

2021
import { cosine, loadLocalEmbedder } from "./localEmbedder.js";
@@ -78,7 +79,9 @@ const CATALOG_ARTIFACT_TIMEOUT_MS = 30_000;
7879
/** Where the bundled vector set lives, overridable for development. */
7980
function localVectorDirectory(): string {
8081
return (
81-
process.env["HYPERFRAMES_CATALOG_ARTIFACT_DIR"] ?? join(homedir(), ".hyperframes", "catalog")
82+
process.env["HYPERFRAMES_CATALOG_ARTIFACT_DIR"] ||
83+
namedCacheDir("catalog") ||
84+
join(homedir(), ".hyperframes", "catalog")
8285
);
8386
}
8487

0 commit comments

Comments
 (0)