mirror of
https://github.com/penpot/penpot.git
synced 2026-11-18 16:12:24 +00:00
* 🐛 Make execute_code wait for save before success * 🐛 Address review feedback on waitForSave Reject with an Error carrying a `code`: save-timeout, rolled-back, save-retrying, or the failure code (save-failed by default). Lower the default timeout from 90s to 60s, leaving room for the 30s layout wait and the code under the MCP tool timeout. When persistence is already in error at the start of the wait, keep the stored failure code, and tell a failure Penpot keeps retrying apart from one that needs the file reopened. Share timeout validation with waitForLayoutUpdate through app.plugins.utils, and make reject-not-valid reject with an Error, which also fixes the string rejections of connectLibrary, restore, remove, pin, export, findVersions and saveVersion. The MCP execute_code handler now waits for the save only when the workspace is ready, like the layout wait, so dashboard calls no longer fail on a save error from an earlier file. Move the waitForSave tests to frontend-tests.plugins, add tests for the error codes, the retrying state and a failure during the wait, and add plugin API suite and MCP handler tests. Update the docs, CHANGELOG and the generated API files. AI-assisted-by: claude-opus-5-5
472 lines
13 KiB
TypeScript
472 lines
13 KiB
TypeScript
import type {
|
|
ActiveUser,
|
|
Board,
|
|
Boolean,
|
|
BooleanType,
|
|
Color,
|
|
ColorShapeInfo,
|
|
Ellipse,
|
|
EventsMap,
|
|
File,
|
|
Flags,
|
|
FontsContext,
|
|
Group,
|
|
HistoryContext,
|
|
LibraryComponent,
|
|
LibraryContext,
|
|
LibraryVariantComponent,
|
|
LocalStorage,
|
|
Page,
|
|
Path,
|
|
Penpot,
|
|
PenpotMgmt,
|
|
Rectangle,
|
|
Shape,
|
|
SvgRaw,
|
|
Text,
|
|
Theme,
|
|
User,
|
|
VariantContainer,
|
|
Viewport,
|
|
} from '@penpot/plugin-types';
|
|
|
|
import { Permissions } from '../models/manifest.model.js';
|
|
import { OpenUIOptions } from '../models/open-ui-options.model.js';
|
|
import { z } from 'zod';
|
|
import { createPluginManager } from '../plugin-manager.js';
|
|
|
|
export const validEvents = [
|
|
'finish',
|
|
'logout',
|
|
'workspacechange',
|
|
'pagechange',
|
|
'filechange',
|
|
'selectionchange',
|
|
'themechange',
|
|
'shapechange',
|
|
'contentsave',
|
|
'contentrollback',
|
|
] as const;
|
|
|
|
export function createApi(
|
|
plugin: Awaited<ReturnType<typeof createPluginManager>>,
|
|
) {
|
|
const workspaceUnavailable = () =>
|
|
plugin.manifest.scope === 'global' &&
|
|
plugin.context.management?.workspace.status !== 'ready';
|
|
|
|
const requireWorkspace = () => {
|
|
if (workspaceUnavailable()) {
|
|
throw new Error(
|
|
'No workspace is ready. Use penpotMgmt.openFile() first.',
|
|
);
|
|
}
|
|
};
|
|
|
|
const checkPermission = (permission: Permissions, workspace = true) => {
|
|
if (!plugin.manifest.permissions.includes(permission)) {
|
|
throw new Error(`Permission ${permission} is not granted`);
|
|
}
|
|
if (workspace && /^(content|library|comment):/.test(permission))
|
|
requireWorkspace();
|
|
};
|
|
|
|
const penpot: Penpot = {
|
|
ui: {
|
|
open: (name: string, url: string, options?: OpenUIOptions) => {
|
|
plugin.openModal(name, url, options);
|
|
},
|
|
|
|
get size() {
|
|
return plugin.getModal()?.size() || null;
|
|
},
|
|
|
|
resize: (width: number, height: number) => {
|
|
return plugin.resizeModal(width, height);
|
|
},
|
|
|
|
sendMessage(message: unknown, throwOnError = false) {
|
|
let cloneableMessage: unknown;
|
|
|
|
try {
|
|
cloneableMessage = structuredClone(message);
|
|
} catch (err) {
|
|
const msg =
|
|
'plugin sendMessage: the message could not be cloned. ' +
|
|
'Ensure the message does not contain functions, DOM nodes, or other non-serializable values.';
|
|
if (throwOnError) {
|
|
throw new Error(
|
|
msg +
|
|
' Original error: ' +
|
|
(err instanceof Error ? err.message : String(err)),
|
|
{ cause: err },
|
|
);
|
|
} else {
|
|
console.error(msg, err);
|
|
}
|
|
return;
|
|
}
|
|
|
|
const event = new CustomEvent('message', {
|
|
detail: cloneableMessage,
|
|
});
|
|
|
|
plugin.getModal()?.dispatchEvent(event);
|
|
},
|
|
|
|
onMessage: <T>(callback: (message: T) => void) => {
|
|
z.function().parse(callback);
|
|
|
|
plugin.registerMessageCallback(callback as (message: unknown) => void);
|
|
},
|
|
},
|
|
|
|
utils: {
|
|
geometry: {
|
|
center(shapes: Shape[]) {
|
|
// eslint-disable-next-line @typescript-eslint/no-explicit-any
|
|
return (window as any).app.plugins.public_utils.centerShapes(shapes);
|
|
},
|
|
},
|
|
types: {
|
|
isBoard(shape: Shape): shape is Board {
|
|
return shape.type === 'board';
|
|
},
|
|
isGroup(shape: Shape): shape is Group {
|
|
return shape.type === 'group';
|
|
},
|
|
isMask(shape: Shape): shape is Group {
|
|
return shape.type === 'group' && shape.isMask();
|
|
},
|
|
isBool(shape: Shape): shape is Boolean {
|
|
return shape.type === 'boolean';
|
|
},
|
|
isRectangle(shape: Shape): shape is Rectangle {
|
|
return shape.type === 'rectangle';
|
|
},
|
|
isPath(shape: Shape): shape is Path {
|
|
return shape.type === 'path';
|
|
},
|
|
isText(shape: Shape): shape is Text {
|
|
return shape.type === 'text';
|
|
},
|
|
isEllipse(shape: Shape): shape is Ellipse {
|
|
return shape.type === 'ellipse';
|
|
},
|
|
isSVG(shape: Shape): shape is SvgRaw {
|
|
return shape.type === 'svg-raw';
|
|
},
|
|
isVariantContainer(shape: Shape): shape is VariantContainer {
|
|
return shape.type === 'board' && shape.isVariantContainer();
|
|
},
|
|
isVariantComponent(
|
|
component: LibraryComponent,
|
|
): component is LibraryVariantComponent {
|
|
return component.isVariant();
|
|
},
|
|
},
|
|
},
|
|
|
|
closePlugin: () => {
|
|
plugin.close();
|
|
},
|
|
on<T extends keyof EventsMap>(
|
|
type: T,
|
|
callback: (event: EventsMap[T]) => void,
|
|
props?: { [key: string]: unknown },
|
|
): symbol {
|
|
// z.function alter fn, so can't use it here
|
|
z.enum(validEvents).parse(type);
|
|
z.function().parse(callback);
|
|
|
|
// To suscribe to events needs the read permission
|
|
checkPermission('content:read', false);
|
|
|
|
return plugin.registerListener(type, callback, props);
|
|
},
|
|
|
|
off(eventId: symbol): void {
|
|
plugin.destroyListener(eventId);
|
|
},
|
|
|
|
// Penpot State API
|
|
|
|
get version(): string {
|
|
return plugin.context.version;
|
|
},
|
|
|
|
get root(): Shape | null {
|
|
checkPermission('content:read', false);
|
|
return workspaceUnavailable() ? null : plugin.context.root;
|
|
},
|
|
|
|
get currentFile(): File | null {
|
|
checkPermission('content:read', false);
|
|
return workspaceUnavailable() ? null : plugin.context.currentFile;
|
|
},
|
|
|
|
get currentPage(): Page | null {
|
|
checkPermission('content:read', false);
|
|
return workspaceUnavailable() ? null : plugin.context.currentPage;
|
|
},
|
|
|
|
get selection(): Shape[] {
|
|
checkPermission('content:read');
|
|
return plugin.context.selection;
|
|
},
|
|
|
|
set selection(value: Shape[]) {
|
|
checkPermission('content:read');
|
|
plugin.context.selection = value;
|
|
},
|
|
|
|
get viewport(): Viewport {
|
|
requireWorkspace();
|
|
return plugin.context.viewport;
|
|
},
|
|
|
|
get history(): HistoryContext {
|
|
requireWorkspace();
|
|
return plugin.context.history;
|
|
},
|
|
|
|
get library(): LibraryContext {
|
|
checkPermission('library:read');
|
|
return plugin.context.library;
|
|
},
|
|
|
|
get fonts(): FontsContext {
|
|
checkPermission('content:read');
|
|
return plugin.context.fonts;
|
|
},
|
|
|
|
get flags(): Flags {
|
|
return plugin.context.flags;
|
|
},
|
|
|
|
get currentUser(): User {
|
|
checkPermission('user:read');
|
|
return plugin.context.currentUser;
|
|
},
|
|
|
|
get activeUsers(): ActiveUser[] {
|
|
checkPermission('user:read');
|
|
return plugin.context.activeUsers;
|
|
},
|
|
|
|
shapesColors(shapes: Shape[]): (Color & ColorShapeInfo)[] {
|
|
checkPermission('content:read');
|
|
return plugin.context.shapesColors(shapes);
|
|
},
|
|
|
|
replaceColor(shapes: Shape[], oldColor: Color, newColor: Color) {
|
|
checkPermission('content:write');
|
|
return plugin.context.replaceColor(shapes, oldColor, newColor);
|
|
},
|
|
|
|
get theme(): Theme {
|
|
return plugin.context.theme;
|
|
},
|
|
|
|
get localStorage(): LocalStorage {
|
|
checkPermission('allow:localstorage');
|
|
return plugin.context.localStorage;
|
|
},
|
|
|
|
createBoard(): Board {
|
|
checkPermission('content:write');
|
|
return plugin.context.createBoard();
|
|
},
|
|
|
|
createRectangle(): Rectangle {
|
|
checkPermission('content:write');
|
|
return plugin.context.createRectangle();
|
|
},
|
|
|
|
createEllipse(): Ellipse {
|
|
checkPermission('content:write');
|
|
return plugin.context.createEllipse();
|
|
},
|
|
|
|
createText(text: string): Text | null {
|
|
checkPermission('content:write');
|
|
return plugin.context.createText(text);
|
|
},
|
|
|
|
createPath(): Path {
|
|
checkPermission('content:write');
|
|
return plugin.context.createPath();
|
|
},
|
|
|
|
createBoolean(boolType: BooleanType, shapes: Shape[]): Boolean | null {
|
|
checkPermission('content:write');
|
|
return plugin.context.createBoolean(boolType, shapes);
|
|
},
|
|
|
|
createShapeFromSvg(svgString: string): Group | null {
|
|
checkPermission('content:write');
|
|
return plugin.context.createShapeFromSvg(svgString);
|
|
},
|
|
|
|
createShapeFromSvgWithImages(svgString: string): Promise<Group | null> {
|
|
checkPermission('content:write');
|
|
return plugin.context.createShapeFromSvgWithImages(svgString);
|
|
},
|
|
|
|
group(shapes: Shape[]): Group | null {
|
|
checkPermission('content:write');
|
|
return plugin.context.group(shapes);
|
|
},
|
|
|
|
ungroup(group: Group, ...other: Group[]): void {
|
|
checkPermission('content:write');
|
|
plugin.context.ungroup(group, ...other);
|
|
},
|
|
|
|
uploadMediaUrl(name: string, url: string) {
|
|
checkPermission('content:write');
|
|
return plugin.context.uploadMediaUrl(name, url);
|
|
},
|
|
|
|
uploadMediaData(name: string, data: Uint8Array, mimeType: string) {
|
|
checkPermission('content:write');
|
|
return plugin.context.uploadMediaData(name, data, mimeType);
|
|
},
|
|
|
|
generateMarkup(
|
|
shapes: Shape[],
|
|
options?: { type?: 'html' | 'svg' },
|
|
): string {
|
|
checkPermission('content:read');
|
|
return plugin.context.generateMarkup(shapes, options);
|
|
},
|
|
|
|
generateStyle(
|
|
shapes: Shape[],
|
|
options?: {
|
|
type?: 'css';
|
|
withPrelude?: boolean;
|
|
includeChildren?: boolean;
|
|
},
|
|
): string {
|
|
checkPermission('content:read');
|
|
return plugin.context.generateStyle(shapes, options);
|
|
},
|
|
|
|
generateFontFaces(shapes: Shape[]): Promise<string> {
|
|
checkPermission('content:read');
|
|
return plugin.context.generateFontFaces(shapes);
|
|
},
|
|
|
|
openViewer(): void {
|
|
checkPermission('content:read');
|
|
plugin.context.openViewer();
|
|
},
|
|
|
|
createPage(): Page {
|
|
checkPermission('content:write');
|
|
return plugin.context.createPage();
|
|
},
|
|
|
|
openPage(page: Page | string, newWindow?: boolean): Promise<void> {
|
|
checkPermission('content:read');
|
|
return plugin.context.openPage(page, newWindow ?? false);
|
|
},
|
|
|
|
alignHorizontal(
|
|
shapes: Shape[],
|
|
direction: 'left' | 'center' | 'right',
|
|
): void {
|
|
checkPermission('content:write');
|
|
plugin.context.alignHorizontal(shapes, direction);
|
|
},
|
|
|
|
alignVertical(
|
|
shapes: Shape[],
|
|
direction: 'top' | 'center' | 'bottom',
|
|
): void {
|
|
checkPermission('content:write');
|
|
plugin.context.alignVertical(shapes, direction);
|
|
},
|
|
|
|
distributeHorizontal(shapes: Shape[]): void {
|
|
checkPermission('content:write');
|
|
plugin.context.distributeHorizontal(shapes);
|
|
},
|
|
|
|
distributeVertical(shapes: Shape[]): void {
|
|
checkPermission('content:write');
|
|
plugin.context.distributeVertical(shapes);
|
|
},
|
|
|
|
flatten(shapes: Shape[]): Path[] {
|
|
checkPermission('content:write');
|
|
return plugin.context.flatten(shapes);
|
|
},
|
|
|
|
createVariantFromComponents(shapes: Board[]): VariantContainer {
|
|
checkPermission('content:write');
|
|
return plugin.context.createVariantFromComponents(shapes);
|
|
},
|
|
|
|
waitForLayoutUpdate(timeout?: number): Promise<void> {
|
|
checkPermission('content:read');
|
|
return plugin.context.waitForLayoutUpdate(timeout);
|
|
},
|
|
|
|
waitForSave(timeout?: number): Promise<void> {
|
|
checkPermission('content:read');
|
|
return plugin.context.waitForSave(timeout);
|
|
},
|
|
};
|
|
|
|
const penpotMgmt: PenpotMgmt = {
|
|
get workspace() {
|
|
checkPermission('content:read', false);
|
|
return plugin.context.management!.workspace;
|
|
},
|
|
listTeams() {
|
|
checkPermission('manage:teams', false);
|
|
return plugin.context.management!.listTeams();
|
|
},
|
|
createTeam(options) {
|
|
checkPermission('manage:teams', false);
|
|
return plugin.context.management!.createTeam(options);
|
|
},
|
|
listProjects(options) {
|
|
checkPermission('content:read', false);
|
|
return plugin.context.management!.listProjects(options);
|
|
},
|
|
listDeletedProjects(options) {
|
|
checkPermission('content:read', false);
|
|
return plugin.context.management!.listDeletedProjects(options);
|
|
},
|
|
listDeletedFiles(options) {
|
|
checkPermission('content:read', false);
|
|
return plugin.context.management!.listDeletedFiles(options);
|
|
},
|
|
getFile(fileId) {
|
|
checkPermission('content:read', false);
|
|
return plugin.context.management!.getFile(fileId);
|
|
},
|
|
openFile(fileId, options) {
|
|
checkPermission('content:read', false);
|
|
return plugin.context.management!.openFile(fileId, options);
|
|
},
|
|
on(type, callback) {
|
|
z.literal('workspacechange').parse(type);
|
|
z.function().parse(callback);
|
|
checkPermission('content:read', false);
|
|
return plugin.registerListener(type, callback);
|
|
},
|
|
off(listenerId) {
|
|
plugin.destroyListener(listenerId);
|
|
},
|
|
};
|
|
|
|
return {
|
|
penpot,
|
|
penpotMgmt,
|
|
};
|
|
}
|