Files
hyperframes/packages/cli/src/commands/add.test.ts
T
Miguel Ángel 0bda6b55b8 feat(cli): track which registry items add installs (#3099)
* 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.
2026-08-07 16:00:23 -07:00

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 });
}
});
});