fix assistant custom widget creation

This commit is contained in:
ajnart committed 2026-08-14 11:32:11 +02:00
1 parent 474d9968b5
commit ceed0979a1
21 files changed
+513 -47

No files matched your search

@@ -0,0 +1,110 @@
import { TRPCError } from "@trpc/server";
import { z } from "zod/v4";
import { createLogger } from "@homarr/core/infrastructure/logs";
import {
customWidgetCreateSchema,
customWidgetDefinitionSchema,
normalizeCustomWidgetAuthoringDefinition,
} from "@homarr/custom-widgets/core";
import { permissionRequiredProcedure } from "../../trpc";
import { parseCustomWidgetAuthoringInput } from "./authoring-validation";
import { insertCustomWidgetDefinition } from "./definition-insert";
import { getPreviewJournal, getPreviewSession, getPreviewSessionSecrets } from "./preview-sessions";
import { assertSecretSources } from "./secret-policy";
const logger = createLogger({ module: "custom-widget" });
const getCreatedCustomWidgetResult = (id: string, targetBoardId?: string) => ({
id,
managementPath: `/manage/custom-widgets/edit/${id}`,
nextAction: {
type: "place-custom-widget" as const,
widgetKind: "customApi" as const,
options: { definitionId: id },
...(targetBoardId ? { targetBoardId } : {}),
whenTargetIsKnown: "Call configure_widget now with the requested board and these exact widget options.",
whenTargetIsUnknown:
"Call ask_user now with 'Place on a board' and 'Leave unplaced'. Never ask this choice in prose.",
},
});
export const creationProcedures = {
create: permissionRequiredProcedure
.requiresPermission("admin")
.meta({
mcp: {
enabled: true,
description:
"Create a Custom JSX widget only after customWidget_validate, customWidget_previewCreate, and every returned preview query succeed. Prefer templateLines for multiline JSX. Returns a client-navigable edit link.",
},
})
.input(customWidgetCreateSchema)
.mutation(async ({ ctx, input }) => {
const { secrets, ...candidate } = input;
const definition = parseCustomWidgetAuthoringInput(() => normalizeCustomWidgetAuthoringDefinition(candidate));
assertSecretSources(definition.sources, secrets);
const id = await insertCustomWidgetDefinition(ctx.db, definition, ctx.session.user.id, secrets);
logger.info("Created custom widget definition", { id, name: definition.name });
return getCreatedCustomWidgetResult(id);
}),
createFromPreview: permissionRequiredProcedure
.requiresPermission("admin")
.meta({
mcp: {
enabled: true,
description:
"Persist the exact tested definition from a customWidget_previewCreate session. Prefer this over resending a large widget to customWidget_create. Every query in the final preview must have a successful customWidget_previewQuery journal entry.",
},
})
.input(z.object({ previewSessionId: z.string().min(1), targetBoardId: z.string().min(1).optional() }))
.mutation(async ({ ctx, input }) => {
const session = await getPreviewSession(input.previewSessionId, ctx.session.user.id);
const journal = await getPreviewJournal(session.id, ctx.session.user.id);
const unverifiedQueryIds = Object.entries(session.requests).flatMap(([requestId, request]) => {
if (request.kind !== "query") return [];
const verified = journal.some(
(entry) =>
entry.kind === "query" &&
entry.requestId === requestId &&
entry.sessionRevision === session.revision &&
entry.status !== null &&
entry.status >= 200 &&
entry.status < 300,
);
return verified ? [] : [requestId];
});
if (unverifiedQueryIds.length > 0) {
throw new TRPCError({
code: "BAD_REQUEST",
message: `Test every final preview query successfully before creating the widget: ${unverifiedQueryIds.join(", ")}`,
});
}
const definition = parseCustomWidgetAuthoringInput(() =>
customWidgetDefinitionSchema.parse({
$schema: "homarr-custom-widget-v2",
name: session.name,
description: session.description,
iconUrl: session.iconUrl,
sources: session.sources,
requests: session.requests,
options: session.optionDefinitions,
template: session.template,
}),
);
const secrets = Object.keys(session.sources).flatMap((sourceId) =>
getPreviewSessionSecrets(session, sourceId).map((secret) => ({ sourceId, ...secret })),
);
assertSecretSources(definition.sources, secrets);
const id = await insertCustomWidgetDefinition(ctx.db, definition, ctx.session.user.id, secrets);
logger.info("Created custom widget definition from tested preview", {
id,
name: definition.name,
previewSessionId: session.id,
});
return getCreatedCustomWidgetResult(id, input.targetBoardId);
}),
};
@@ -108,7 +108,8 @@ export const metadataProcedures = {
.query(({ input }) => {
const example = getCustomWidgetExample(input.name);
if (!example) throw new TRPCError({ code: "NOT_FOUND", message: "Custom JSX example not found" });
return example;
const { template, ...widget } = example.widget;
return { ...example, widget: { ...widget, templateLines: template.split("\n") } };
}),
validate: permissionRequiredProcedure
@@ -109,6 +109,8 @@ const previewCreateProcedure = permissionRequiredProcedure
sources: definition.sources,
requests: definition.requests,
name: definition.name,
description: definition.description,
iconUrl: definition.iconUrl,
template: definition.template,
optionDefinitions: definition.options,
options,
@@ -145,6 +147,8 @@ export const previewBaseProcedures = {
return {
id: session.id,
name: session.name,
description: session.description,
iconUrl: session.iconUrl,
expiresAt: session.expiresAt,
template: session.template,
optionDefinitions: session.optionDefinitions,
@@ -95,8 +95,8 @@ export const setPreviewSessionLiveActions = (id: string, userId: string, enabled
call(() => getService().setLiveActions(id, userId, enabled));
export const appendPreviewJournal = (
session: CustomWidgetPreviewSession,
entry: Omit<CustomWidgetPreviewJournalEntry, "id" | "timestamp">,
) => call(() => getService().appendJournal(session, entry));
entry: Omit<CustomWidgetPreviewJournalEntry, "id" | "sessionRevision" | "timestamp">,
) => call(() => getService().appendJournal(session, { ...entry, sessionRevision: session.revision }));
export const getPreviewJournal = (id: string, userId: string) => call(() => getService().getJournal(id, userId));
export const getPreviewSessionSecrets = (session: CustomWidgetPreviewSession, sourceId: string) =>
getService().getSecrets(session, sourceId);
@@ -15,6 +15,11 @@ import { describe, expect, test } from "vitest";
import { customWidgetRouter } from "../../custom-widget/custom-widget-router";
import { getCustomWidgetConfigurationRequestForUser } from "../../custom-widget/configuration-requests";
import { configureCustomWidgetSourceFromRequest } from "../../custom-widget/secret-persistence";
import {
appendPreviewJournal,
configurePreviewSessionSource,
getPreviewSession,
} from "../../custom-widget/preview-sessions";
import { serializeCustomWidgetDefinition } from "../../custom-widget/stored-definition";
const userId = createId();
@@ -33,6 +38,8 @@ const nonAdminSession = {
const jellyfin = BUNDLED_CUSTOM_WIDGETS.find(({ id }) => id === "seed-jellyfin")?.widget;
if (!jellyfin) throw new Error("Jellyfin bundled widget is missing");
const pokedex = BUNDLED_CUSTOM_WIDGETS.find(({ id }) => id === "seed-pokedex")?.widget;
if (!pokedex) throw new Error("Pokédex bundled widget is missing");
const jellyfinDefaultSource = jellyfin.sources.default;
if (!jellyfinDefaultSource) throw new Error("Jellyfin default source is missing");
@@ -142,6 +149,69 @@ describe("custom widget definition persistence", () => {
expect((await caller.get({ id: created.id })).template).toBe(template);
});
test("persists the exact final tested Pokédex preview without resending its JSX", async () => {
const db = await prepareDatabase();
const caller = createCaller(db);
const { template, ...definition } = pokedex;
const candidate = { ...definition, templateLines: template.split("\n") };
// A long-running authoring request can iterate several times. Only the final preview session
// is eligible for persistence, and its compact ID replaces a second large streamed payload.
await caller.previewCreate({ definition: candidate, secrets: [] });
await caller.previewCreate({ definition: candidate, secrets: [] });
const finalPreview = await caller.previewCreate({ definition: candidate, secrets: [] });
const createInput = { previewSessionId: finalPreview.previewSession.id, targetBoardId: "board-hey" };
expect(Buffer.byteLength(JSON.stringify(createInput), "utf8")).toBeLessThan(128);
await expect(caller.createFromPreview(createInput)).rejects.toThrow("Test every final preview query successfully");
const previewSession = await getPreviewSession(finalPreview.previewSession.id, userId);
for (const [requestId, request] of Object.entries(previewSession.requests)) {
if (request.kind !== "query") continue;
await appendPreviewJournal(previewSession, {
requestId,
kind: "query",
method: request.method,
path: request.path,
status: 200,
durationMs: 1,
simulated: false,
});
}
const defaultSource = previewSession.sources.default;
if (!defaultSource) throw new Error("Pokédex preview source is missing");
await configurePreviewSessionSource(previewSession.id, userId, "default", { ...defaultSource }, []);
await expect(caller.createFromPreview(createInput)).rejects.toThrow("Test every final preview query successfully");
const finalPreviewSession = await getPreviewSession(finalPreview.previewSession.id, userId);
for (const [requestId, request] of Object.entries(finalPreviewSession.requests)) {
if (request.kind !== "query") continue;
await appendPreviewJournal(finalPreviewSession, {
requestId,
kind: "query",
method: request.method,
path: request.path,
status: 200,
durationMs: 1,
simulated: false,
});
}
const created = await caller.createFromPreview(createInput);
expect(created.managementPath).toBe(`/manage/custom-widgets/edit/${created.id}`);
expect(created.nextAction.options).toEqual({ definitionId: created.id });
expect(created.nextAction.targetBoardId).toBe("board-hey");
await expect(caller.get({ id: created.id })).resolves.toMatchObject({
name: pokedex.name,
description: pokedex.description,
template,
sources: pokedex.sources,
requests: pokedex.requests,
options: pokedex.options,
});
});
test("updates a saved widget with MCP-friendly multiline templateLines", async () => {
const db = await prepareDatabase();
const caller = createCaller(db);
@@ -129,7 +129,7 @@ export const CUSTOM_WIDGET_MCP_AUTHORING_PROMPT = `Author one Homarr Custom JSX
First call customWidget_getSkill. Its single lazy response contains the complete installed SKILL.md and every bundled reference; follow all of it. Read the live schema and compact component catalog. Fetch only the named component and example resources needed for the design. Component resources contain component-specific props; if shared props are needed, collect their catalog names and fetch those docs together once with customWidget_getSharedProps. The live resources are authoritative for this Homarr release.
Follow this lifecycle without skipping steps: construct one credential-free definition; call customWidget_validate; repair every reported issue; call customWidget_previewCreate; call customWidget_previewQuery once for every query returned by that preview (supplying required manual parameters); inspect the real response shape and HTTP status; adjust paths and template bindings; validate and preview again after changes; open or provide the returned previewPath for visual review; only then call customWidget_create. Prefer templateLines over a JSON-escaped template string for multiline JSX in validate, preview, and create tool inputs.
Follow this lifecycle without skipping steps: construct one credential-free definition; call customWidget_validate; repair every reported issue; call customWidget_previewCreate; call customWidget_previewQuery once for every query returned by that preview (supplying required manual parameters); inspect the real response shape and HTTP status; adjust paths and template bindings; validate and preview again after changes; open or provide the returned previewPath for visual review; only then call customWidget_createFromPreview with the exact final tested preview session ID. Use customWidget_create only when no reusable preview session exists. Prefer templateLines over a JSON-escaped template string for multiline JSX in validate and preview tool inputs.
Do not claim a query works when it has not returned a successful preview response. Configure deployment-specific source URLs and request credentials through Homarr when needed; never repeat plaintext. Use simulated preview actions unless the user explicitly enables live preview actions.
@@ -3,6 +3,7 @@ import {
customJsxCatalogGlobalPropByName,
resolveCustomJsxPropDescriptor,
} from "./component-catalog";
import { BUNDLED_CUSTOM_WIDGETS } from "./bundled-widgets";
import { customJsxExamples } from "./examples";
import { customJsxTablerIconNames } from "./tabler-icons";
@@ -11,7 +12,7 @@ export const CUSTOM_WIDGET_SKILL_SOURCE_URL =
"https://github.com/homarr-labs/homarr/tree/HEAD/.agents/skills/homarr-custom-widget";
export const CUSTOM_WIDGET_SKILL_INSTALL_COMMAND =
"npx skills add https://github.com/homarr-labs/homarr --skill homarr-custom-widget";
export const CUSTOM_WIDGET_SKILL_VERSION = "2.2.0";
export const CUSTOM_WIDGET_SKILL_VERSION = "2.3.0";
export const CUSTOM_WIDGET_SKILL_REFERENCES = {
"references/schema.md": `# Schema
@@ -77,7 +78,7 @@ Author one widget at a time. When connected to Homarr, retrieve \`homarr://custo
2. Create one credential-free widget with keyed \`sources\`, keyed \`requests\`, optional keyed \`options\`, and safe JSX \`template\`.
3. Validate, preview, test queries and simulated actions, visually inspect, and iterate.
4. Configure deployment-specific source URLs and request credentials through Homarr; never repeat plaintext.
5. Save only after narrow/wide, light/dark, loading, empty, error, and success states work.
5. Save only after narrow/wide, light/dark, loading, empty, error, and success states work. When connected through MCP, persist the exact final tested preview with \`customWidget_createFromPreview\`; do not resend a large template through \`customWidget_create\` unless no preview session is available.
Use \`{option:name}\` or \`$option\` for saved options. Use \`{param:name}\` or \`$param\` for values supplied by \`SubFetch\`, \`ActionButton\`, or \`ToggleSwitch\`. Load queries cannot use invocation parameters. Templates read \`data\`, \`status\`, \`options\`, and temporary \`inputs\`.
@@ -101,6 +102,8 @@ const CUSTOM_WIDGET_SKILL_BUNDLE_MD = [
),
].join("");
const pokedexAuthoringExample = BUNDLED_CUSTOM_WIDGETS.find(({ id }) => id === "seed-pokedex");
export function getCustomWidgetSkill() {
return {
name: "homarr-custom-widget",
@@ -135,7 +138,19 @@ export function getCustomWidgetComponentCatalog() {
}
export function getCustomWidgetExampleCatalog() {
return customJsxExamples.map(({ id, title, description }) => ({ id, title, description }));
return [
...customJsxExamples.map(({ id, title, description }) => ({ id, title, description })),
...(pokedexAuthoringExample
? [
{
id: "pokedex",
title: "Complete Pokédex",
description:
"A production-safe PokéAPI browser with searchable species, artwork, types, abilities, base stats, loading states, and manual detail requests.",
},
]
: []),
];
}
export function getCustomWidgetComponent(name: string) {
@@ -183,5 +198,14 @@ export function getCustomWidgetSharedProps(names: readonly string[]) {
}
export function getCustomWidgetExample(name: string) {
if (name === "pokedex" && pokedexAuthoringExample) {
return {
id: "pokedex",
title: "Complete Pokédex",
description:
"A production-safe PokéAPI browser with searchable species, artwork, types, abilities, base stats, loading states, and manual detail requests.",
widget: pokedexAuthoringExample.widget,
};
}
return customJsxExamples.find((example) => example.id === name) ?? null;
}
@@ -29,6 +29,8 @@ const sessionSchema = z.object({
secrets: z.array(encryptedSecretSchema),
requests: customWidgetRequestsSchema,
name: z.string(),
description: z.string().optional(),
iconUrl: z.string().optional(),
template: z.string(),
optionDefinitions: customWidgetOptionsSchema,
options: z.record(z.string(), z.unknown()),
@@ -46,6 +48,7 @@ const journalEntrySchema = z.object({
status: z.number().nullable(),
durationMs: z.number().nonnegative(),
simulated: z.boolean(),
sessionRevision: z.number().int().nonnegative(),
timestamp: z.number(),
});
export type CustomWidgetPreviewJournalEntry = z.infer<typeof journalEntrySchema>;
@@ -56,6 +59,8 @@ export interface CreatePreviewSessionInput {
secrets: Array<{ sourceId: string; kind: (typeof customWidgetSecretKinds)[number]; value: string }>;
requests: Record<string, CustomJsxRequest>;
name: string;
description?: string;
iconUrl?: string;
template: string;
optionDefinitions: CustomWidgetOptions;
options: Record<string, unknown>;
@@ -105,6 +110,8 @@ export class CustomWidgetPreviewSessionService {
secrets: input.secrets.map((secret) => ({ ...secret, value: this.options.encrypt(secret.value) })),
requests: input.requests,
name: input.name,
description: input.description,
iconUrl: input.iconUrl,
template: input.template,
optionDefinitions: input.optionDefinitions,
options: input.options,
@@ -45,6 +45,7 @@ describe("AI prompt", () => {
expect(CUSTOM_WIDGET_MCP_AUTHORING_PROMPT).toContain("customWidget_validate");
expect(CUSTOM_WIDGET_MCP_AUTHORING_PROMPT).toContain("customWidget_previewCreate");
expect(CUSTOM_WIDGET_MCP_AUTHORING_PROMPT).toContain("customWidget_previewQuery once for every query");
expect(CUSTOM_WIDGET_MCP_AUTHORING_PROMPT).toContain("customWidget_createFromPreview");
expect(CUSTOM_WIDGET_MCP_AUTHORING_PROMPT).toContain("customWidget_getSharedProps");
expect(CUSTOM_WIDGET_MCP_AUTHORING_PROMPT).toContain("Prefer templateLines");
expect(CUSTOM_WIDGET_MCP_AUTHORING_PROMPT.indexOf("customWidget_previewQuery")).toBeLessThan(
@@ -5,6 +5,7 @@ import { describe, expect, it } from "vitest";
import {
getCustomWidgetComponent,
getCustomWidgetComponentCatalog,
getCustomWidgetExample,
getCustomWidgetSharedProps,
getCustomWidgetSkill,
getCustomWidgetSkillContent,
@@ -15,7 +16,7 @@ const skillSourceDirectory = path.resolve(import.meta.dirname, "../../../../.age
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.2.0" });
expect(skill).toMatchObject({ name: "homarr-custom-widget", version: "2.3.0" });
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");
@@ -40,6 +41,17 @@ describe("authoring resources", () => {
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" } },
},
});
expect(Buffer.byteLength(JSON.stringify(pokedex), "utf8")).toBeLessThan(16_000);
expect(catalog.sharedProps).toMatchObject({
count: expect.any(Number),
fetchTool: "customWidget_getSharedProps",
@@ -64,8 +64,13 @@ describe("preview sessions", () => {
status: 200,
durationMs: 5,
simulated: false,
sessionRevision: session.revision,
});
expect((await service.getJournal(created.id, "user"))[0]).toMatchObject({
path: "/data",
status: 200,
sessionRevision: session.revision,
});
expect((await service.getJournal(created.id, "user"))[0]).toMatchObject({ path: "/data", status: 200 });
});
it("applies source deployment values without restoring stale source metadata", async () => {