mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-11-19 11:26:02 +00:00
* feat(cli): track which registry items `add` installs `cli_command` records that `add` ran and nothing about what it installed, and the registry is served from raw.githubusercontent.com, which gives no per-item counter either — so there is no way to tell which block or component people actually pull, and no way to know what is worth building more of. Emit one `registry_item_added` event per item written into a project, from `runAdd` after the install succeeds. That is the single choke point: the bulk `add <tag>` path re-enters it per item, and a failed or compatibility-refused install throws before it, so a refused install is never counted as a download. `requested` separates the item the user named from the transitive `registryDependencies` pulled in behind it; without it a popular dependency outranks everything that depends on it. Item names are public registry identifiers, never user content or project data, and the event goes through `trackEvent` — an install that opted out via `hyperframes telemetry disable`, `HYPERFRAMES_NO_TELEMETRY` or `DO_NOT_TRACK` sends nothing. * test(cli): cover `add` telemetry end to end against the built CLI The unit tests assert the emit seam and nothing past it. `shouldTrack()` short-circuits whenever `isDevMode()` is true, and that is true for any `.ts` entry, so under vitest a real event and no event are indistinguishable and the transport is never exercised at all. Drive the built CLI instead and assert on the HTTP body it actually produces: one event per installed item, the dependency reported with `requested: false`, an opted-out install sending no request at all (not merely one without this event), and a refused install counting nothing. Two fixtures, because neither case is reachable through the real registry. The registry origin is a first-class project setting, so a local one supplies the `registryDependencies` edge that no shipped catalog item declares today; and `globalThis.fetch` is wrapped to capture the batch rather than send it. The faked 200 is load-bearing: only a failed flush leaves events queued, and only a non-empty queue spawns the detached `flushSync` child that would bypass the hook and reach production analytics. Verified the check can fail — forcing `requested: true` for every item turns it red on exactly the dependency assertion.
427 lines
14 KiB
TypeScript
427 lines
14 KiB
TypeScript
import { describe, expect, it, vi, beforeEach, afterEach } from "vitest";
|
|
import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
|
|
import { tmpdir } from "node:os";
|
|
import { join } from "node:path";
|
|
import type { RegistryItem, RegistryManifest } from "@hyperframes/core";
|
|
import { AddError, buildSnippet, remapTarget, runAdd } from "./add.js";
|
|
import { trackRegistryItemAdded } from "../telemetry/events.js";
|
|
|
|
// Assert the emitted payload rather than the transport: `shouldTrack()` is
|
|
// already false under test (dev mode / no PostHog key), so a real call would
|
|
// be indistinguishable from no call at all.
|
|
vi.mock("../telemetry/events.js", () => ({ trackRegistryItemAdded: vi.fn() }));
|
|
|
|
// ── Fixtures ────────────────────────────────────────────────────────────────
|
|
|
|
const MANIFEST: RegistryManifest = {
|
|
$schema: "https://hyperframes.heygen.com/schema/registry.json",
|
|
name: "test",
|
|
homepage: "https://example.com",
|
|
items: [
|
|
{ name: "my-block", type: "hyperframes:block" },
|
|
{ name: "deprecated-block", type: "hyperframes:block" },
|
|
{ name: "future-block", type: "hyperframes:block" },
|
|
{ name: "dep-block", type: "hyperframes:block" },
|
|
{ name: "base-component", type: "hyperframes:component" },
|
|
{ name: "my-component", type: "hyperframes:component" },
|
|
{ name: "my-example", type: "hyperframes:example" },
|
|
],
|
|
};
|
|
|
|
const BLOCK_ITEM: RegistryItem = {
|
|
$schema: "https://hyperframes.heygen.com/schema/registry-item.json",
|
|
name: "my-block",
|
|
type: "hyperframes:block",
|
|
title: "My Block",
|
|
description: "Block for tests",
|
|
dimensions: { width: 1080, height: 1350 },
|
|
duration: 6,
|
|
files: [
|
|
{
|
|
path: "my-block.html",
|
|
target: "compositions/my-block.html",
|
|
type: "hyperframes:composition",
|
|
},
|
|
],
|
|
};
|
|
|
|
const COMPONENT_ITEM: RegistryItem = {
|
|
$schema: "https://hyperframes.heygen.com/schema/registry-item.json",
|
|
name: "my-component",
|
|
type: "hyperframes:component",
|
|
title: "My Component",
|
|
description: "Component for tests",
|
|
files: [
|
|
{
|
|
path: "my-component.html",
|
|
target: "compositions/components/my-component/my-component.html",
|
|
type: "hyperframes:snippet",
|
|
},
|
|
{
|
|
path: "my-component.css",
|
|
target: "compositions/components/my-component/my-component.css",
|
|
type: "hyperframes:style",
|
|
},
|
|
{
|
|
path: "assets/mask.png",
|
|
target: "assets/my-component/mask.png",
|
|
type: "hyperframes:asset",
|
|
},
|
|
],
|
|
};
|
|
|
|
const DEPRECATED_BLOCK_ITEM: RegistryItem = {
|
|
...BLOCK_ITEM,
|
|
name: "deprecated-block",
|
|
title: "Deprecated Block",
|
|
deprecated: "Use `my-block` instead.",
|
|
files: [
|
|
{
|
|
path: "deprecated-block.html",
|
|
target: "compositions/deprecated-block.html",
|
|
type: "hyperframes:composition",
|
|
},
|
|
],
|
|
};
|
|
|
|
const FUTURE_BLOCK_ITEM: RegistryItem = {
|
|
...BLOCK_ITEM,
|
|
name: "future-block",
|
|
title: "Future Block",
|
|
minCliVersion: "999.0.0",
|
|
files: [
|
|
{
|
|
path: "future-block.html",
|
|
target: "compositions/future-block.html",
|
|
type: "hyperframes:composition",
|
|
},
|
|
],
|
|
};
|
|
|
|
const BASE_COMPONENT_ITEM: RegistryItem = {
|
|
$schema: "https://hyperframes.heygen.com/schema/registry-item.json",
|
|
name: "base-component",
|
|
type: "hyperframes:component",
|
|
title: "Base Component",
|
|
description: "Base component dependency for tests",
|
|
files: [
|
|
{
|
|
path: "base-component.css",
|
|
target: "compositions/components/base-component/base-component.css",
|
|
type: "hyperframes:style",
|
|
},
|
|
],
|
|
};
|
|
|
|
// A block that declares a transitive registryDependency on base-component.
|
|
const DEP_BLOCK_ITEM: RegistryItem = {
|
|
...BLOCK_ITEM,
|
|
name: "dep-block",
|
|
title: "Dependent Block",
|
|
registryDependencies: ["base-component"],
|
|
files: [
|
|
{
|
|
path: "dep-block.html",
|
|
target: "compositions/dep-block.html",
|
|
type: "hyperframes:composition",
|
|
},
|
|
],
|
|
};
|
|
|
|
const EXAMPLE_ITEM: RegistryItem = {
|
|
$schema: "https://hyperframes.heygen.com/schema/registry-item.json",
|
|
name: "my-example",
|
|
type: "hyperframes:example",
|
|
title: "My Example",
|
|
description: "Example for tests",
|
|
dimensions: { width: 1920, height: 1080 },
|
|
duration: 10,
|
|
files: [{ path: "index.html", target: "index.html", type: "hyperframes:composition" }],
|
|
};
|
|
|
|
const ITEM_BY_NAME: Record<string, RegistryItem> = {
|
|
"my-block": BLOCK_ITEM,
|
|
"deprecated-block": DEPRECATED_BLOCK_ITEM,
|
|
"future-block": FUTURE_BLOCK_ITEM,
|
|
"dep-block": DEP_BLOCK_ITEM,
|
|
"base-component": BASE_COMPONENT_ITEM,
|
|
"my-component": COMPONENT_ITEM,
|
|
"my-example": EXAMPLE_ITEM,
|
|
};
|
|
|
|
function mockFetch(): void {
|
|
vi.stubGlobal(
|
|
"fetch",
|
|
vi.fn(async (input: string | URL) => {
|
|
const url = typeof input === "string" ? input : input.toString();
|
|
if (url.endsWith("/registry.json")) {
|
|
return new Response(JSON.stringify(MANIFEST), { status: 200 });
|
|
}
|
|
const m = /\/(examples|blocks|components)\/([^/]+)\/registry-item\.json$/.exec(url);
|
|
if (m) {
|
|
const item = ITEM_BY_NAME[m[2]!];
|
|
if (item) return new Response(JSON.stringify(item), { status: 200 });
|
|
}
|
|
// File fetch — match `/<type-dir>/<name>/<rest>` and serve synthetic content.
|
|
const f = /\/(examples|blocks|components)\/([^/]+)\/(.+)$/.exec(url);
|
|
if (f) {
|
|
return new Response(`/* ${f[3]} */\n`, { status: 200 });
|
|
}
|
|
return new Response("not found", { status: 404 });
|
|
}),
|
|
);
|
|
}
|
|
|
|
function tmp(): string {
|
|
return mkdtempSync(join(tmpdir(), "hf-add-test-"));
|
|
}
|
|
|
|
function uniqueBase(): string {
|
|
return `https://test.invalid/${crypto.randomUUID()}`;
|
|
}
|
|
|
|
const DEFAULT_TEST_PATHS = {
|
|
blocks: "compositions",
|
|
components: "compositions/components",
|
|
assets: "assets",
|
|
};
|
|
|
|
function writeRegistryConfig(
|
|
dir: string,
|
|
paths: typeof DEFAULT_TEST_PATHS = DEFAULT_TEST_PATHS,
|
|
): void {
|
|
writeFileSync(
|
|
join(dir, "hyperframes.json"),
|
|
JSON.stringify({
|
|
$schema: "https://hyperframes.heygen.com/schema/hyperframes.json",
|
|
registry: uniqueBase(),
|
|
paths,
|
|
}),
|
|
"utf-8",
|
|
);
|
|
}
|
|
|
|
// ── Tests ───────────────────────────────────────────────────────────────────
|
|
|
|
describe("add command pure helpers", () => {
|
|
describe("remapTarget", () => {
|
|
const PATHS = { blocks: "src/scenes", components: "src/fx" };
|
|
|
|
it("rewrites block default path to paths.blocks", () => {
|
|
expect(remapTarget(BLOCK_ITEM, "compositions/my-block.html", PATHS)).toBe(
|
|
"src/scenes/my-block.html",
|
|
);
|
|
});
|
|
|
|
it("rewrites component default path to paths.components", () => {
|
|
expect(
|
|
remapTarget(
|
|
COMPONENT_ITEM,
|
|
"compositions/components/my-component/my-component.html",
|
|
PATHS,
|
|
),
|
|
).toBe("src/fx/my-component/my-component.html");
|
|
});
|
|
|
|
it("leaves example targets alone", () => {
|
|
expect(remapTarget(EXAMPLE_ITEM, "index.html", PATHS)).toBe("index.html");
|
|
});
|
|
|
|
it("leaves non-default block paths alone (no blind string replace)", () => {
|
|
// A block's manifest could in future use a non-default target — make
|
|
// sure the prefix match is anchored.
|
|
expect(remapTarget(BLOCK_ITEM, "elsewhere/my-block.html", PATHS)).toBe(
|
|
"elsewhere/my-block.html",
|
|
);
|
|
});
|
|
});
|
|
|
|
describe("buildSnippet", () => {
|
|
it("wraps blocks in a div with data-composition-src and duration", () => {
|
|
const snip = buildSnippet(BLOCK_ITEM, "src/scenes/my-block.html");
|
|
expect(snip).toContain('data-composition-src="src/scenes/my-block.html"');
|
|
expect(snip).toContain('data-duration="6"');
|
|
});
|
|
|
|
it("emits a paste hint for components", () => {
|
|
const snip = buildSnippet(COMPONENT_ITEM, "src/fx/my-component/my-component.html");
|
|
expect(snip).toContain("paste from");
|
|
expect(snip).toContain("my-component.html");
|
|
});
|
|
|
|
it("returns empty string for examples", () => {
|
|
expect(buildSnippet(EXAMPLE_ITEM, "index.html")).toBe("");
|
|
});
|
|
});
|
|
});
|
|
|
|
describe("runAdd (integration, mocked registry)", () => {
|
|
beforeEach(() => {
|
|
vi.mocked(trackRegistryItemAdded).mockClear();
|
|
mockFetch();
|
|
});
|
|
afterEach(() => {
|
|
vi.unstubAllGlobals();
|
|
});
|
|
|
|
it("installs a block into the default compositions/ path and returns the snippet", async () => {
|
|
const dir = tmp();
|
|
try {
|
|
// Write hyperframes.json so runAdd uses our unique baseUrl.
|
|
writeRegistryConfig(dir);
|
|
|
|
const result = await runAdd({ name: "my-block", projectDir: dir, skipClipboard: true });
|
|
expect(result.ok).toBe(true);
|
|
expect(result.name).toBe("my-block");
|
|
expect(result.type).toBe("hyperframes:block");
|
|
expect(result.written).toHaveLength(1);
|
|
expect(result.installed).toEqual(["my-block"]);
|
|
expect(result.warnings).toEqual([]);
|
|
expect(existsSync(join(dir, "compositions/my-block.html"))).toBe(true);
|
|
const installed = readFileSync(join(dir, "compositions/my-block.html"), "utf-8");
|
|
expect(installed).toContain("<!-- hyperframes-registry-item: my-block -->");
|
|
expect(installed).toContain("my-block.html");
|
|
expect(result.snippet).toContain("compositions/my-block.html");
|
|
} finally {
|
|
rmSync(dir, { recursive: true, force: true });
|
|
}
|
|
});
|
|
|
|
it("returns a warning for deprecated registry items while still installing", async () => {
|
|
const dir = tmp();
|
|
try {
|
|
writeRegistryConfig(dir);
|
|
|
|
const result = await runAdd({
|
|
name: "deprecated-block",
|
|
projectDir: dir,
|
|
skipClipboard: true,
|
|
});
|
|
expect(result.warnings).toEqual([
|
|
'Registry item "deprecated-block" is deprecated: Use `my-block` instead.',
|
|
]);
|
|
expect(existsSync(join(dir, "compositions/deprecated-block.html"))).toBe(true);
|
|
} finally {
|
|
rmSync(dir, { recursive: true, force: true });
|
|
}
|
|
});
|
|
|
|
it("blocks registry items that require a newer CLI before writing files", async () => {
|
|
const dir = tmp();
|
|
try {
|
|
writeRegistryConfig(dir);
|
|
|
|
await expect(
|
|
runAdd({
|
|
name: "future-block",
|
|
projectDir: dir,
|
|
skipClipboard: true,
|
|
cliVersion: "0.6.79",
|
|
}),
|
|
).rejects.toMatchObject({
|
|
code: "incompatible-cli",
|
|
});
|
|
expect(existsSync(join(dir, "compositions/future-block.html"))).toBe(false);
|
|
// Nothing was written, so nothing may be counted: an install count that
|
|
// also counts refused installs is not a download count.
|
|
expect(trackRegistryItemAdded).not.toHaveBeenCalled();
|
|
} finally {
|
|
rmSync(dir, { recursive: true, force: true });
|
|
}
|
|
});
|
|
|
|
it("remaps component snippet/style targets while leaving asset targets stable", async () => {
|
|
const dir = tmp();
|
|
try {
|
|
writeRegistryConfig(dir, { blocks: "compositions", components: "src/fx", assets: "assets" });
|
|
|
|
const result = await runAdd({
|
|
name: "my-component",
|
|
projectDir: dir,
|
|
skipClipboard: true,
|
|
});
|
|
expect(result.written.length).toBe(3);
|
|
expect(existsSync(join(dir, "src/fx/my-component/my-component.html"))).toBe(true);
|
|
expect(existsSync(join(dir, "src/fx/my-component/my-component.css"))).toBe(true);
|
|
expect(existsSync(join(dir, "assets/my-component/mask.png"))).toBe(true);
|
|
expect(result.snippet).toContain("src/fx/my-component/my-component.html");
|
|
} finally {
|
|
rmSync(dir, { recursive: true, force: true });
|
|
}
|
|
});
|
|
|
|
it("installs transitive registryDependencies before the requested item", async () => {
|
|
const dir = tmp();
|
|
try {
|
|
writeRegistryConfig(dir);
|
|
|
|
const result = await runAdd({ name: "dep-block", projectDir: dir, skipClipboard: true });
|
|
expect(result.name).toBe("dep-block");
|
|
// Dependency first, requested item last.
|
|
expect(result.installed).toEqual(["base-component", "dep-block"]);
|
|
expect(result.written).toHaveLength(2);
|
|
expect(
|
|
existsSync(join(dir, "compositions/components/base-component/base-component.css")),
|
|
).toBe(true);
|
|
expect(existsSync(join(dir, "compositions/dep-block.html"))).toBe(true);
|
|
// Snippet points at the requested block, not the dependency.
|
|
expect(result.snippet).toContain("compositions/dep-block.html");
|
|
} finally {
|
|
rmSync(dir, { recursive: true, force: true });
|
|
}
|
|
});
|
|
|
|
it("reports every installed item, marking only the requested one", async () => {
|
|
const dir = tmp();
|
|
try {
|
|
writeRegistryConfig(dir);
|
|
|
|
await runAdd({ name: "dep-block", projectDir: dir, skipClipboard: true });
|
|
|
|
// A dependency dragged in behind the request must not read as a vote for
|
|
// itself, or a popular dependency outranks everything that depends on it.
|
|
expect(trackRegistryItemAdded).toHaveBeenCalledTimes(2);
|
|
expect(trackRegistryItemAdded).toHaveBeenCalledWith({
|
|
item: "base-component",
|
|
itemType: "hyperframes:component",
|
|
requested: false,
|
|
});
|
|
expect(trackRegistryItemAdded).toHaveBeenCalledWith({
|
|
item: "dep-block",
|
|
itemType: "hyperframes:block",
|
|
requested: true,
|
|
});
|
|
} finally {
|
|
rmSync(dir, { recursive: true, force: true });
|
|
}
|
|
});
|
|
|
|
it("throws AddError with code 'example-type' when asked to add an example", async () => {
|
|
const dir = tmp();
|
|
try {
|
|
writeRegistryConfig(dir);
|
|
|
|
await expect(
|
|
runAdd({ name: "my-example", projectDir: dir, skipClipboard: true }),
|
|
).rejects.toMatchObject({
|
|
code: "example-type",
|
|
});
|
|
} finally {
|
|
rmSync(dir, { recursive: true, force: true });
|
|
}
|
|
});
|
|
|
|
it("throws AddError with code 'unknown-item' for a missing name", async () => {
|
|
const dir = tmp();
|
|
try {
|
|
writeRegistryConfig(dir);
|
|
|
|
await expect(
|
|
runAdd({ name: "nope", projectDir: dir, skipClipboard: true }),
|
|
).rejects.toBeInstanceOf(AddError);
|
|
} finally {
|
|
rmSync(dir, { recursive: true, force: true });
|
|
}
|
|
});
|
|
});
|