fix: cache paths follow HYPERFRAMES_CACHE_DIR by miguel-heygen · Pull Request #6716 · heygen-com/hyperframes

miguel-heygen · 2026-10-29T04:48:23Z

What changed

Every place the CLI and its packages keep downloaded or built files (the headless browser, whisper and Parakeet models, background-removal models, TTS, optional packages, fonts, cloud asset records, the Lambda handler, warm-check state, project history) now takes its folder from one helper, hyperframesCacheDir() in @hyperframes/core/cache-dir.
Cache paths follow HYPERFRAMES_CACHE_DIR when it is set. The default is unchanged: ~/.cache/hyperframes, so existing caches and CI caches keyed on that path keep working.
A host that runs the CLI (HyperFrames Desktop, for one) can keep its own cache apart from the one in the home folder.
The CLI docs mention the variable.

How

packages/core/src/cacheDir.ts: hyperframesCacheDir(...parts) reads the variable on each call and resolves a relative value.
20 call sites in cli, core, engine, inspector and studio-server now use it in place of join(homedir(), ".cache", "hyperframes", …).
packages/core/src/cacheDir.test.ts checks the default and the override, and scans every package's sources so a new hand-built cache path fails the test.

What I measured

Linux x64: tsc --noEmit exit 0 in core, engine, inspector and studio-server; cli reports no error in any file this changes (its remaining errors come from unbuilt workspace packages). oxlint, oxfmt --check and fallow audit are clean on the 21 changed files.
packages/core/src/cacheDir.test.ts: 3 passed. fails without the fix: writing one site back by hand (tts/manager.ts) turns the scan red, naming that file.
The existing tests of every changed file pass, among them whisper/* (49), tts/* (25), browser/manager, background-removal/*, cloud/offload, utils/optionalPackages, warmCheck*, the deterministicFonts-* and fontCompression suites (245), browserManager* (132) and projectHistory* (154).
The commit hooks were run as above rather than locally.

What I did NOT exercise

A real download or install into a moved cache folder; the call sites only change where the folder is.
Windows. Warm-check state there still lives under LOCALAPPDATA, and on Linux under XDG_RUNTIME_DIR when set; only the fallback follows the variable.

Every place HyperFrames keeps downloaded or built files now takes its folder from one helper, hyperframesCacheDir() in @hyperframes/core. The default stays ~/.cache/hyperframes; HYPERFRAMES_CACHE_DIR moves it.

mintlify · 2026-10-29T04:48:26Z

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated
hyperframes	🟢 Ready	View Preview	Oct 29, 2026, 5:28 AM

💡 Tip: Enable Automations to automatically generate PRs for you.

github-actions · 2026-10-29T04:53:09Z

Edit accuracy: accurate 271 (base branch 271), smooth 185 of those

The gate passes.
Smoothness is reported in the artifact, not gated. A case fails only if it fails 2 of 3 runs.

Quarantined, measured but not gated (0)

heygengenesis

Verdict: REQUEST CHANGES · 3 blocker · 0 important · 1 nit · head dabb0f5b

The helper and the 20 call sites look right, and the guard scan found no remaining hand-built paths. The blockers are all CI. Comments, Lint/Preflight, Build and Fallow fail because of this PR. Regression, preview, player-perf and Windows are red only because their preflight is. ↓ inline

nit: a relative HYPERFRAMES_CACHE_DIR resolves against the cwd at import time for the module-level constants (CACHE_DIR, MODELS_DIR, …). The warm-check server imports them in its own cwd and only then calls process.chdir(request.cwd) (cli/src/warmCheck.ts:57). A warm run can therefore use a different folder than a cold one. Consider documenting that the variable should be absolute.

Scope

Read every changed file, grepped the tree at head for leftover .cache paths (only the torch and huggingface ones remain, which is correct), and checked child-process env propagation and the warm-check env digest. The fails without the fix: line names cacheDir.test.ts, which is acceptable. Studio: edit accuracy gate is also red; re-check it once the build passes.

— Genesis

heygengenesis · 2026-10-29T05:01:37Z

      "import": "./src/atomicFile.ts",
      "types": "./src/atomicFile.ts"
    },
+    "./cache-dir": {


blocker: ./cache-dir is in package.json but not in packages/core/package-subpaths.json, so check:package-subpaths fails Lint and every Preflight ("package.json is out of sync"). The descriptor's default environments are browser+node, which is why verify:packed-manifests (Build) tries to bundle dist/cacheDir.js for the browser and fails on node:path. Add the entry next to ./atomic-file with "environments": ["bun", "node"], then run bun run sync:package-subpaths.

Fixed in 51a321f: ./cache-dir is in package-subpaths.json next to ./atomic-file, with "environments": ["bun", "node"]. check:package-subpaths passes (14 public workspaces). I could not run verify:packed-manifests to the end locally (it stops at an unbuilt package before core), so CI's Build is the check for that.

heygengenesis · 2026-10-29T05:01:37Z

 import { closeServer } from "./pageServer";
 import { Sources, fingerprint } from "./sources";
 import type { InspectRequest, Snippet } from "./types";
+import { hyperframesCacheDir } from "@hyperframes/core/cache-dir";


blocker: this is inspector's first @hyperframes/core subpath import. Its esbuild build (platform: "node") resolves the node condition to dist/cacheDir.js, and core's dist isn't built when Fallow's "Build generated inspector inputs" step runs: Could not resolve "@hyperframes/core/cache-dir". Import it relatively like the runtime-inline import above (../../core/src/cacheDir), or build core first.

Fixed in 51a321f: inspector imports ../../core/src/cacheDir, like the htmlBundler import above it. Its build passes with packages/core/dist moved aside, in the same order as the CI step (parsers and lint, the runtime, then inspector).

heygengenesis · 2026-10-29T05:01:37Z

+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+
+/** Where HyperFrames keeps what it downloads, builds and caches: `HYPERFRAMES_CACHE_DIR` when set, else


blocker: the Comments ratchet fails here: "NEW file over its package's comment share: cacheDir.ts is 20.0% (2/10), the package is 12.6%". Drop the docblock; the name and the test already say it.

Fixed in 51a321f: the docblock is gone. On the nit: the docs now say to set HYPERFRAMES_CACHE_DIR to an absolute path, since module-level constants resolve a relative value against the working directory at import time.

…ctor from core source

heygengenesis

Verdict: REQUEST CHANGES — 3 resolved, 0 open, 1 new · dabb0f5b → 51a321f5

All three earlier blockers and the nit are fixed. Previously the Windows lanes stopped at preflight; now they run, and Tests on windows-latest: core fails on the new test. ↓ inline

— Genesis

heygengenesis · 2026-10-29T05:49:49Z

+
+  it("follows HYPERFRAMES_CACHE_DIR, read on each call, a relative one resolved", () => {
+    vi.stubEnv("HYPERFRAMES_CACHE_DIR", "/elsewhere/cache");
+    expect(hyperframesCacheDir("whisper", "models")).toBe(


blocker: this fails on Windows (Tests on windows-latest: core): expected 'D:\\elsewhere\\cache\\whisper\\models' to be '\\elsewhere\\cache\\whisper\\models'. /elsewhere/cache isn't absolute there, so resolve adds the drive. The helper is right; fix the expectation, e.g. use an absolute dir from tmpdir(), or expect join(resolve("/elsewhere/cache"), "whisper", "models").

Fixed in 411eb17: the override test now uses an absolute folder under tmpdir() and expects join(elsewhere, "whisper", "models"), so no drive letter is added on Windows. Passes on Linux (3/3); the Windows core lane in CI checks the rest.

…very platform

heygengenesis

Verdict: APPROVE — 1 resolved, 0 open, 0 new · 51a321f5 → 411eb179. Only the test changed: it now uses an absolute temp folder. All CI is green, including Tests on windows-latest: core.

— Genesis

fix: cache paths follow HYPERFRAMES_CACHE_DIR

dabb0f5

Every place HyperFrames keeps downloaded or built files now takes its folder from one helper, hyperframesCacheDir() in @hyperframes/core. The default stays ~/.cache/hyperframes; HYPERFRAMES_CACHE_DIR moves it.

mintlify Bot deployed to staging - docs October 29, 2026 04:54

View deployment

heygengenesis Bot requested changes Oct 29, 2026

View reviewed changes

fix: register the cache-dir subpath for bun and node, and build inspe…

51a321f

…ctor from core source

mintlify Bot deployed to staging - docs October 29, 2026 05:28

View deployment

heygengenesis Bot requested changes Oct 29, 2026

View reviewed changes

test: the cache-dir override test uses a folder that is absolute on e…

411eb17

…very platform

heygengenesis Bot approved these changes Oct 29, 2026

View reviewed changes

miguel-heygen enabled auto-merge October 29, 2026 06:17

Conversation

miguel-heygen commented Oct 29, 2026

What changed

How

What I measured

What I did NOT exercise

Uh oh!

mintlify Bot commented Oct 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Oct 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Edit accuracy: accurate 271 (base branch 271), smooth 185 of those

Uh oh!

heygengenesis Bot left a comment

Choose a reason for hiding this comment

Uh oh!

heygengenesis Bot Oct 29, 2026

Choose a reason for hiding this comment

Uh oh!

miguel-heygen Oct 29, 2026

Choose a reason for hiding this comment

Uh oh!

heygengenesis Bot Oct 29, 2026

Choose a reason for hiding this comment

Uh oh!

miguel-heygen Oct 29, 2026

Choose a reason for hiding this comment

Uh oh!

heygengenesis Bot Oct 29, 2026

Choose a reason for hiding this comment

Uh oh!

miguel-heygen Oct 29, 2026

Choose a reason for hiding this comment

Uh oh!

heygengenesis Bot left a comment

Choose a reason for hiding this comment

Uh oh!

heygengenesis Bot Oct 29, 2026

Choose a reason for hiding this comment

Uh oh!

miguel-heygen Oct 29, 2026

Choose a reason for hiding this comment

Uh oh!

heygengenesis Bot left a comment

Choose a reason for hiding this comment

Uh oh!

This branch was successfully deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

mintlify Bot commented Oct 29, 2026 •

edited

Loading

github-actions Bot commented Oct 29, 2026 •

edited

Loading