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"; // ── 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 = { "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 `///` 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(() => 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(""); 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); } 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("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 }); } }); });