Files
hyperframes/packages/cli/src/registry/remote.test.ts
T
Miguel Ángel ecf0e14387 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
2026-11-05 10:56:35 +00:00

467 lines
18 KiB
TypeScript

import { afterAll, afterEach, beforeEach, describe, expect, it, vi } from "vitest";
import type { MockInstance } from "vitest";
import { mkdtempSync, rmSync, readdirSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
// The cache lives under homedir(), so the whole suite runs against a scratch
// home rather than the developer's own ~/.hyperframes.
const scratchHome = mkdtempSync(join(tmpdir(), "hf-remote-"));
vi.mock("node:os", async (importOriginal) => ({
...(await importOriginal<typeof import("node:os")>()),
homedir: () => scratchHome,
}));
const {
assetSourceUrl,
fetchItemFile,
fetchItemManifest,
fetchRegistryManifest,
readRegistryManifest,
DEFAULT_REGISTRY_URL,
} = await import("./remote.js");
const MANIFEST = {
name: "hyperframes",
homepage: "https://hyperframes.heygen.com",
items: [{ name: "count-up", type: "hyperframes:component" }],
};
const ITEM = {
name: "count-up",
type: "hyperframes:component",
title: "Count up",
description: "Counter",
files: [{ path: "count.html", target: "count.html", type: "hyperframes:snippet" }],
};
const ONE_DAY_MS = 24 * 60 * 60 * 1000;
function ok(body: unknown): Response {
return new Response(JSON.stringify(body));
}
/**
* Prime the cache with one good fetch, then jump past the 24h TTL with every
* later fetch failing: the exact shape of "the registry host stopped answering
* and the copy on disk is a day old". Returns the failing spy so a caller can
* assert the network was actually attempted — without that the fallback
* assertions pass even if the clock never moved.
*/
async function staleAfterPriming(
body: unknown,
prime: () => Promise<unknown>,
): Promise<MockInstance<typeof fetch>> {
vi.spyOn(globalThis, "fetch").mockResolvedValueOnce(ok(body));
await prime();
vi.useFakeTimers({ shouldAdvanceTime: true });
vi.setSystemTime(new Date(Date.now() + ONE_DAY_MS + 60_000));
return vi
.spyOn(globalThis, "fetch")
.mockClear()
.mockRejectedValue(new Error("The operation was aborted"));
}
beforeEach(() => {
rmSync(join(scratchHome, ".hyperframes"), { recursive: true, force: true });
vi.restoreAllMocks();
vi.useRealTimers();
});
afterEach(() => {
vi.useRealTimers();
});
afterAll(() => {
rmSync(scratchHome, { recursive: true, force: true });
});
describe("readRegistryManifest", () => {
it("throws why when the registry host cannot be reached and nothing is cached", async () => {
vi.spyOn(globalThis, "fetch").mockRejectedValue(
Object.assign(new TypeError("fetch failed"), {
cause: Object.assign(new Error("getaddrinfo ENOTFOUND raw.githubusercontent.com"), {
code: "ENOTFOUND",
}),
}),
);
await expect(readRegistryManifest(DEFAULT_REGISTRY_URL)).rejects.toThrow(
"The registry could not be read: fetch failed (getaddrinfo ENOTFOUND raw.githubusercontent.com)",
);
});
});
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);
const cache = join(scratchHome, ".hyperframes/cache");
const file = readdirSync(cache)[0]!;
writeFileSync(
join(cache, file),
JSON.stringify({
fetchedAt: 0,
data: { ...MANIFEST, items: [{ name: "../../outside", type: "hyperframes:component" }] },
}),
);
vi.spyOn(globalThis, "fetch").mockRejectedValue(new Error("offline"));
await expect(fetchRegistryManifest(DEFAULT_REGISTRY_URL)).resolves.toBeUndefined();
});
it("serves a fresh cache without touching the network", async () => {
const fetchSpy = vi.spyOn(globalThis, "fetch").mockResolvedValue(ok(MANIFEST));
await fetchRegistryManifest(DEFAULT_REGISTRY_URL);
expect(fetchSpy).toHaveBeenCalledTimes(1);
const second = await fetchRegistryManifest(DEFAULT_REGISTRY_URL);
expect(second).toEqual(MANIFEST);
expect(fetchSpy).toHaveBeenCalledTimes(1);
});
it("serves the expired cache when the registry host times out", async () => {
// The failure this exists for: raw.githubusercontent.com stops answering,
// the entry is a day and a bit old, and before this fix the caller was
// told the whole catalog was unreachable while a usable copy sat on disk.
const fetchSpy = await staleAfterPriming(MANIFEST, () =>
fetchRegistryManifest(DEFAULT_REGISTRY_URL),
);
await expect(fetchRegistryManifest(DEFAULT_REGISTRY_URL)).resolves.toEqual(MANIFEST);
expect(fetchSpy).toHaveBeenCalledTimes(1);
});
it("treats an empty cached payload as a miss rather than an answer", async () => {
// The callers test the entry, not the payload, so a file carrying a valid
// fetchedAt and a null body would otherwise short-circuit the fetch and be
// handed back as a manifest.
vi.spyOn(globalThis, "fetch").mockResolvedValueOnce(ok(null));
await fetchRegistryManifest(DEFAULT_REGISTRY_URL);
const fetchSpy = vi.spyOn(globalThis, "fetch").mockClear().mockResolvedValue(ok(MANIFEST));
await expect(fetchRegistryManifest(DEFAULT_REGISTRY_URL)).resolves.toEqual(MANIFEST);
expect(fetchSpy).toHaveBeenCalledTimes(1);
});
it("still reports unreachable when the network fails and nothing was cached", async () => {
vi.spyOn(globalThis, "fetch").mockRejectedValue(new Error("getaddrinfo ENOTFOUND"));
await expect(fetchRegistryManifest(DEFAULT_REGISTRY_URL)).resolves.toBeUndefined();
});
it("falls back to the stale copy under skipCache too", async () => {
// skipCache asks for something newer. It has never meant "rather have
// nothing than this", so a failed revalidation must not empty the result.
vi.spyOn(globalThis, "fetch").mockResolvedValueOnce(ok(MANIFEST));
await fetchRegistryManifest(DEFAULT_REGISTRY_URL);
vi.spyOn(globalThis, "fetch").mockRejectedValue(new Error("HTTP 503"));
await expect(fetchRegistryManifest(DEFAULT_REGISTRY_URL, { skipCache: true })).resolves.toEqual(
MANIFEST,
);
});
it("prefers a successful refetch over the cached copy", async () => {
vi.spyOn(globalThis, "fetch").mockResolvedValueOnce(ok(MANIFEST));
await fetchRegistryManifest(DEFAULT_REGISTRY_URL);
const fresher = {
...MANIFEST,
items: [
{ name: "count-up", type: "hyperframes:component" },
{ name: "push-in", type: "hyperframes:component" },
],
};
vi.spyOn(globalThis, "fetch").mockResolvedValue(ok(fresher));
await expect(fetchRegistryManifest(DEFAULT_REGISTRY_URL, { skipCache: true })).resolves.toEqual(
fresher,
);
});
});
describe("fetchItemManifest", () => {
it("refreshes a fresh item cache when skipCache is requested", async () => {
const fetchSpy = vi.spyOn(globalThis, "fetch").mockResolvedValueOnce(ok(ITEM));
await fetchItemManifest("count-up", "hyperframes:component");
const updated = {
...ITEM,
title: "Updated counter",
files: [{ path: "updated.html", target: "updated.html", type: "hyperframes:snippet" }],
};
fetchSpy.mockResolvedValue(ok(updated)).mockClear();
await expect(
fetchItemManifest("count-up", "hyperframes:component", DEFAULT_REGISTRY_URL, {
skipCache: true,
}),
).resolves.toEqual(updated);
expect(fetchSpy).toHaveBeenCalledOnce();
await expect(fetchItemManifest("count-up", "hyperframes:component")).resolves.toEqual(updated);
expect(fetchSpy).toHaveBeenCalledOnce();
});
it("keeps using a fresh item cache without skipCache", async () => {
const fetchSpy = vi.spyOn(globalThis, "fetch").mockResolvedValueOnce(ok(ITEM));
await fetchItemManifest("count-up", "hyperframes:component");
fetchSpy.mockResolvedValue(ok({ ...ITEM, title: "Updated counter" })).mockClear();
await expect(fetchItemManifest("count-up", "hyperframes:component")).resolves.toEqual(ITEM);
expect(fetchSpy).not.toHaveBeenCalled();
});
it.each([0, ONE_DAY_MS + 60_000])(
"keeps refresh requests offline in cache-only mode with cache age %d",
async (age) => {
const fetchSpy = vi.spyOn(globalThis, "fetch").mockResolvedValueOnce(ok(ITEM));
await fetchItemManifest("count-up", "hyperframes:component");
vi.useFakeTimers();
vi.setSystemTime(new Date(Date.now() + age));
fetchSpy.mockRejectedValue(new Error("offline")).mockClear();
await expect(
fetchItemManifest("count-up", "hyperframes:component", DEFAULT_REGISTRY_URL, {
skipCache: true,
cacheOnly: true,
}),
).resolves.toEqual(ITEM);
expect(fetchSpy).not.toHaveBeenCalled();
},
);
it("does not refresh an uncached item in cache-only mode", async () => {
const fetchSpy = vi.spyOn(globalThis, "fetch").mockResolvedValue(ok(ITEM));
await expect(
fetchItemManifest("count-up", "hyperframes:component", DEFAULT_REGISTRY_URL, {
skipCache: true,
cacheOnly: true,
}),
).rejects.toThrow("not fetched after an earlier registry timeout");
expect(fetchSpy).not.toHaveBeenCalled();
});
it("serves the cached item when a forced refresh fails", async () => {
const fetchSpy = vi.spyOn(globalThis, "fetch").mockResolvedValueOnce(ok(ITEM));
await fetchItemManifest("count-up", "hyperframes:component");
fetchSpy.mockRejectedValue(new Error("HTTP 503")).mockClear();
await expect(
fetchItemManifest("count-up", "hyperframes:component", DEFAULT_REGISTRY_URL, {
skipCache: true,
}),
).resolves.toEqual(ITEM);
expect(fetchSpy).toHaveBeenCalledOnce();
});
it("keeps a valid cached item when a forced refresh returns invalid data", async () => {
const fetchSpy = vi.spyOn(globalThis, "fetch").mockResolvedValueOnce(ok(ITEM));
await fetchItemManifest("count-up", "hyperframes:component");
fetchSpy.mockResolvedValue(ok({ ...ITEM, name: "different-item" })).mockClear();
await expect(
fetchItemManifest("count-up", "hyperframes:component", DEFAULT_REGISTRY_URL, {
skipCache: true,
}),
).resolves.toEqual(ITEM);
expect(fetchSpy).toHaveBeenCalledOnce();
await expect(fetchItemManifest("count-up", "hyperframes:component")).resolves.toEqual(ITEM);
expect(fetchSpy).toHaveBeenCalledOnce();
});
it("rejects a cache escape name before fetching", async () => {
const fetchSpy = vi.spyOn(globalThis, "fetch");
await expect(
fetchItemManifest("x/../../../.config/tool", "hyperframes:component"),
).rejects.toThrow(/Invalid registry item/);
expect(fetchSpy).not.toHaveBeenCalled();
});
it("rejects a response for a different requested item", async () => {
vi.spyOn(globalThis, "fetch").mockResolvedValue(ok(ITEM));
await expect(fetchItemManifest("other", "hyperframes:component")).rejects.toThrow(
/Invalid registry manifest/,
);
});
it("cancels oversized manifest responses without materializing their bodies", async () => {
const cancel = vi.fn();
const response = new Response(new ReadableStream({ cancel }), {
headers: { "content-length": "20000000" },
});
vi.spyOn(globalThis, "fetch").mockResolvedValue(response);
await expect(fetchItemManifest("count-up", "hyperframes:component")).rejects.toThrow(
/download limit/,
);
expect(cancel).toHaveBeenCalledOnce();
});
it("serves the expired cache when the item fetch fails", async () => {
const fetchSpy = await staleAfterPriming(ITEM, () =>
fetchItemManifest("count-up", "hyperframes:component", DEFAULT_REGISTRY_URL),
);
await expect(
fetchItemManifest("count-up", "hyperframes:component", DEFAULT_REGISTRY_URL),
).resolves.toEqual(ITEM);
expect(fetchSpy).toHaveBeenCalledTimes(1);
});
it("still throws when the item fetch fails and nothing was cached", async () => {
// The documented contract for a genuinely unknown item, unchanged: callers
// that install by name have to be able to tell "offline" from "no such item".
vi.spyOn(globalThis, "fetch").mockRejectedValue(new Error("The operation was aborted"));
await expect(
fetchItemManifest("never-fetched", "hyperframes:component", DEFAULT_REGISTRY_URL),
).rejects.toThrow("The operation was aborted");
});
it("surfaces an HTTP error for an item that does not exist", async () => {
vi.spyOn(globalThis, "fetch").mockResolvedValue({
ok: false,
status: 404,
json: async () => ({}),
} as unknown as Response);
await expect(
fetchItemManifest("no-such-move", "hyperframes:component", DEFAULT_REGISTRY_URL),
).rejects.toThrow("HTTP 404");
});
});
describe("assetSourceUrl", () => {
const item = { name: "carousel-orbit-1", type: "hyperframes:block" } as never;
it("resolves a plain file against the registry base", () => {
const file = { path: "carousel-orbit-1.html" } as never;
expect(assetSourceUrl(item, file, "https://registry.example")).toBe(
"https://registry.example/blocks/carousel-orbit-1/carousel-orbit-1.html",
);
});
it("fetches a hosted asset from its own URL, not from the registry base", () => {
// The bug this guards: joining the base to an absolute URL yields
// "https://registry.example/blocks/…/https://cdn.example/…", which 404s
// with a message no reader can act on.
const file = {
path: "assets/carousel-images/one.jpg",
url: "https://cdn.example/registry-assets/deadbeefdeadbeef.jpg",
} as never;
expect(assetSourceUrl(item, file, "https://registry.example")).toBe(
"https://cdn.example/registry-assets/deadbeefdeadbeef.jpg",
);
});
it("refuses a url that is not absolute https, rather than silently mis-joining it", () => {
const file = { path: "assets/one.jpg", url: "http://cdn.example/one.jpg" } as never;
expect(() => assetSourceUrl(item, file, "https://registry.example")).toThrow(
/must be an absolute https:\/\/ URL/,
);
});
});
describe("bounded registry file downloads", () => {
it.each([undefined, "1"])(
"cancels bodies exceeding the shared budget despite length %s",
async (length) => {
const cancel = vi.fn();
vi.spyOn(globalThis, "fetch").mockResolvedValue(
new Response(
new ReadableStream({
pull(controller) {
controller.enqueue(new Uint8Array(4));
},
cancel,
}),
{ headers: length ? { "content-length": length } : {} },
),
);
const budget = { remainingBytes: 5 };
await expect(
fetchItemFile(ITEM as never, ITEM.files[0] as never, DEFAULT_REGISTRY_URL, budget),
).rejects.toThrow(/budget/);
expect(budget.remainingBytes).toBe(0);
expect(cancel).toHaveBeenCalledOnce();
},
);
it("shares the byte budget across concurrent files", async () => {
vi.spyOn(globalThis, "fetch").mockImplementation(async () => new Response("12345678"));
const budget = { remainingBytes: 10 };
const outcomes = await Promise.allSettled(
[1, 2].map(() =>
fetchItemFile(ITEM as never, ITEM.files[0] as never, DEFAULT_REGISTRY_URL, budget),
),
);
expect(outcomes.filter((result) => result.status === "fulfilled")).toHaveLength(1);
expect(budget.remainingBytes).toBe(0);
});
});
describe("fetchItemFile retries", () => {
const item = { name: "blur-in", type: "hyperframes:component" } as never;
const file = { path: "blur-in.html", target: "compositions/components/blur-in.html" } as never;
it("recovers from a transient blip instead of failing the whole install", async () => {
// Item files are the one uncached path, so a single blip used to kill the
// command outright. Two cheap retries is a better trade than that.
const fetchSpy = vi
.spyOn(globalThis, "fetch")
.mockRejectedValueOnce(new Error("fetch failed", { cause: new Error("ECONNRESET") }))
.mockResolvedValueOnce(new Response("<div>ok</div>"));
await expect(fetchItemFile(item, file, DEFAULT_REGISTRY_URL)).resolves.toEqual(
Buffer.from("<div>ok</div>"),
);
expect(fetchSpy).toHaveBeenCalledTimes(2);
});
it("does not retry a certificate failure, which fails identically every time", async () => {
// The reported case: a private registry with a self-signed certificate.
// Retrying only makes the user wait three times as long for one answer.
const fetchSpy = vi.spyOn(globalThis, "fetch").mockRejectedValue(
new Error("fetch failed", {
cause: new Error("self-signed certificate in certificate chain"),
}),
);
await expect(fetchItemFile(item, file, DEFAULT_REGISTRY_URL)).rejects.toThrow(
/self-signed certificate/,
);
expect(fetchSpy).toHaveBeenCalledTimes(1);
});
it("names the URL it could not reach", async () => {
vi.spyOn(globalThis, "fetch").mockRejectedValue(
new Error("fetch failed", { cause: new Error("self-signed certificate in chain") }),
);
await expect(fetchItemFile(item, file, "https://private.example/registry")).rejects.toThrow(
/https:\/\/private\.example\/registry\/components\/blur-in\/blur-in\.html/,
);
});
it("gives up after a bounded number of attempts", async () => {
const fetchSpy = vi
.spyOn(globalThis, "fetch")
.mockRejectedValue(new Error("fetch failed", { cause: new Error("ECONNRESET") }));
await expect(fetchItemFile(item, file, DEFAULT_REGISTRY_URL)).rejects.toThrow();
expect(fetchSpy).toHaveBeenCalledTimes(3);
});
});