import { readFileSync } from "node:fs"; import path from "node:path"; import { describe, expect, it } from "vitest"; import { findCustomWidgetComponents, getCustomWidgetComponent, getCustomWidgetComponentCatalog, getCustomWidgetComponents, getCustomWidgetContextRequestKey, getCustomWidgetExample, getCustomWidgetSharedProps, getCustomWidgetSkill, getCustomWidgetSkillContent, getCustomWidgetSkillEntrypoint, getCustomWidgetSkillReference, } from "../core/authoring-resources"; import { validateCustomJsxTemplate } from "../jsx/analyzer"; const skillSourceDirectory = path.resolve(import.meta.dirname, "../../../../.agents/skills/homarr-custom-widget"); describe("authoring resources", () => { it("returns the complete portable skill and keeps every bundled source file in sync", () => { const skill = getCustomWidgetSkill(); expect(skill).toMatchObject({ name: "homarr-custom-widget", version: "2.10.8" }); expect(skill.skillsShUrl).toContain("skills.sh/homarr-labs/homarr"); expect(skill.sourceUrl).toContain("/tree/HEAD/.agents/skills/homarr-custom-widget"); expect(skill.installCommand).toContain("--skill homarr-custom-widget"); expect(skill).not.toHaveProperty("componentCatalog"); expect(skill).not.toHaveProperty("entrypointMd"); expect(skill).not.toHaveProperty("bundledMarkdown"); expect(skill.skillMd.trim()).toBe(readFileSync(path.join(skillSourceDirectory, "SKILL.md"), "utf8").trim()); const bundledContent = getCustomWidgetSkillContent(); for (const [file, content] of Object.entries(skill.references)) { expect(content.trim()).toBe(readFileSync(path.join(skillSourceDirectory, file), "utf8").trim()); expect(bundledContent).toContain(`# Bundled file: ${file}`); expect(bundledContent).toContain(content.trim()); } expect(bundledContent).toContain(skill.skillMd.trim()); expect(Buffer.byteLength(JSON.stringify(skill), "utf8")).toBeLessThan(12_000); const entrypoint = getCustomWidgetSkillEntrypoint(); expect(entrypoint.references).toEqual( expect.arrayContaining([expect.objectContaining({ name: "runtime", tool: "customWidget_getReference" })]), ); expect(JSON.stringify(entrypoint)).not.toContain("# Runtime"); const schemaReference = getCustomWidgetSkillReference("schema").content; expect(Buffer.byteLength(schemaReference, "utf8")).toBeLessThan(4_000); expect(Buffer.byteLength(JSON.stringify(entrypoint), "utf8")).toBeLessThan(3_000); expect(Buffer.byteLength(JSON.stringify(entrypoint), "utf8")).toBeLessThan( Buffer.byteLength(JSON.stringify(skill), "utf8") / 3, ); }); it("keeps catalog discovery compact and component details lazy", () => { const catalog = getCustomWidgetComponentCatalog(); expect(catalog.components.length).toBeGreaterThan(100); expect(catalog.components).toEqual( expect.arrayContaining([expect.objectContaining({ name: "Stack", category: expect.any(String) })]), ); expect(catalog.examples).toEqual(expect.arrayContaining([expect.objectContaining({ id: "service-dashboard" })])); expect(catalog.examples).toEqual(expect.arrayContaining([expect.objectContaining({ id: "pokedex" })])); const pokedex = getCustomWidgetExample("pokedex"); expect(pokedex).toMatchObject({ id: "pokedex", widget: { $schema: "homarr-custom-widget-v2", name: "Pokédex", sources: { default: { baseUrl: "https://pokeapi.co" } }, }, }); const serviceDashboard = getCustomWidgetExample("service-dashboard"); if (!serviceDashboard) throw new Error("Service dashboard example is missing"); expect(validateCustomJsxTemplate(serviceDashboard.widget.template)).toEqual([]); expect(Buffer.byteLength(JSON.stringify(pokedex), "utf8")).toBeLessThan(16_000); expect(catalog.sharedProps).toMatchObject({ count: expect.any(Number), fetchTool: "customWidget_getSharedProps", maxPerRequest: 64, }); expect(catalog.sharedProps.names).toContain("p"); expect(Buffer.byteLength(JSON.stringify(catalog), "utf8")).toBeLessThan(45_000); const stack = getCustomWidgetComponent("Stack"); expect(stack).toMatchObject({ name: "Stack", sharedProps: { fetchTool: "customWidget_getSharedProps" }, }); expect(stack?.props.some(({ source }) => source === "global")).toBe(false); expect(Buffer.byteLength(JSON.stringify(stack), "utf8")).toBeLessThan(20_000); expect(getCustomWidgetComponent("Icon")?.knownValues?.name.length).toBeGreaterThan(100); const largestComponentPayload = Math.max( ...catalog.components.map(({ name }) => Buffer.byteLength(JSON.stringify(getCustomWidgetComponent(name)), "utf8"), ), ); expect(largestComponentPayload).toBeLessThan(20_000); }); it("finds a focused component subset without sending the full catalog", () => { const result = findCustomWidgetComponents("TextInput SubFetch Image Card ActionButton", 12); const oversizedRequest = findCustomWidgetComponents("layout input action chart image status", 40); expect(result.components.map(({ name }) => name)).toEqual( expect.arrayContaining(["TextInput", "SubFetch", "Image", "Card", "ActionButton"]), ); expect(result.components).toHaveLength(12); expect(result.nextStep).toContain("customWidget_getComponent"); expect(Buffer.byteLength(JSON.stringify(result), "utf8")).toBeLessThan(6_000); expect(Buffer.byteLength(JSON.stringify(result), "utf8")).toBeLessThan( Buffer.byteLength(JSON.stringify(getCustomWidgetComponentCatalog()), "utf8") / 5, ); expect(oversizedRequest.components.length).toBeLessThanOrEqual(16); }); it("batches selected component documentation without limiting the complete library", () => { const result = getCustomWidgetComponents([ "SubFetch", "ActionButton", "TextInput", "Pagination", "SubFetch", "Missing", ]); expect(result.components.map(({ name }) => name)).toEqual(["SubFetch", "ActionButton", "TextInput", "Pagination"]); expect(result.components.find(({ name }) => name === "SubFetch")).toHaveProperty("props"); expect(result.components.find(({ name }) => name === "TextInput")).toMatchObject({ bind: { type: "string", initialProp: "defaultValue", resetProp: "resetKey" }, propNames: expect.arrayContaining(["label", "description"]), fullDetailsTool: "customWidget_getComponent", }); expect(result.components.find(({ name }) => name === "TextInput")).not.toHaveProperty("props"); expect(result.notFound).toEqual(["Missing"]); expect(result.nextStep).toContain("preview creation"); expect(Buffer.byteLength(JSON.stringify(result), "utf8")).toBeLessThan(10_000); }); it("identifies duplicate reloadable context requests independent of name order", () => { expect(getCustomWidgetContextRequestKey("customWidget_getReference", { name: "schema" })).toBe( 'customWidget_getReference:{"name":"schema"}', ); expect(getCustomWidgetContextRequestKey("customWidget_getComponents", { names: ["Text", "Badge", "Text"] })).toBe( getCustomWidgetContextRequestKey("customWidget_getComponents", { names: ["Badge", "Text"] }), ); expect(getCustomWidgetContextRequestKey("customWidget_previewCreate", { definition: {} })).toBeNull(); }); it("returns only requested shared prop documentation in one bounded payload", () => { const result = getCustomWidgetSharedProps(["p", "m", "not-a-shared-prop", "p"]); expect(result.props.map(({ name }) => name)).toEqual(["p", "m"]); expect(result.notFound).toEqual(["not-a-shared-prop"]); expect(Buffer.byteLength(JSON.stringify(result), "utf8")).toBeLessThan(4_000); const boundedBatch = getCustomWidgetSharedProps(getCustomWidgetComponentCatalog().sharedProps.names.slice(0, 64)); expect(Buffer.byteLength(JSON.stringify(boundedBatch), "utf8")).toBeLessThan(15_000); }); });