@pixi-board/board-plugin-canvas 0.1.0

package/src/index.ts

@@ -0,0 +1,497 @@
+import type {
+  McpCreateNodeInput,
+  McpUpdateAssetInput,
+  McpUpdateNodeInput,
+  McpWriteCommand,
+  ModelAssetFormat,
+} from "@canvas/board-domain";
+import type { BoardPlugin, BoardTool, JSONSchema } from "@canvas/board-plugin-sdk";
+import { toAssetDto, toNodeDto, toSnapshotDto } from "./dto";
+import { BoardToolUserError } from "./errors";
+import { filterNodes } from "./filter";
+import {
+  getAssetOrThrow,
+  getNodeOrThrow,
+  getOriginAssetForNode,
+  loadProject,
+} from "./reader";
+import { listKnownProjects } from "./projects";
+import { sendWriteCommand } from "./writerClient";
+
+const PROJECT_ROOT_DESCRIPTION = 'Canvas project root absolute path, or "active" for the current canvas';
+const ASSET_KIND_VALUES = ["image", "video", "audio", "model", "text", "markdown", "html", "importing", "generating"] as const;
+const NODE_TYPE_VALUES = ASSET_KIND_VALUES;
+const MODEL_FORMAT_VALUES: ModelAssetFormat[] = [
+  "glb",
+  "gltf",
+  "obj",
+  "fbx",
+  "stl",
+  "ply",
+  "dae",
+  "3mf",
+  "3ds",
+  "vrml",
+  "wrl",
+  "zip",
+];
+
+const anyOutputSchema = {
+  type: "object",
+  additionalProperties: true,
+};
+
+export const canvasPlugin: BoardPlugin = {
+  name: "@pixi-board/board-plugin-canvas",
+  version: "0.1.0",
+  register(api) {
+    for (const tool of canvasTools) {
+      api.registerTool(tool);
+    }
+  },
+};
+
+export const plugin = canvasPlugin;
+
+export const canvasTools: BoardTool[] = [
+  tool({
+    name: "canvas.get_project_list",
+    description: "List known canvas projects from the shared canvas project registry.",
+    inputSchema: objectSchema({}, []),
+    async run() {
+      return {
+        projects: await listKnownProjects(),
+      };
+    },
+  }),
+  tool({
+    name: "canvas.get_board_snapshot",
+    description: "Read a compact board snapshot from local project files. Does not require the desktop app.",
+    inputSchema: objectSchema({
+      projectRoot: stringSchema(PROJECT_ROOT_DESCRIPTION),
+    }),
+    async run(input) {
+      const project = await loadProject(readString(input, "projectRoot"));
+      return toSnapshotDto(project.root, project.snapshot);
+    },
+  }),
+  tool({
+    name: "canvas.list_nodes",
+    description: "List compact board nodes, optionally filtered by bounds or keyword.",
+    inputSchema: objectSchema({
+      projectRoot: stringSchema(PROJECT_ROOT_DESCRIPTION),
+      filter: {
+        type: "object",
+        additionalProperties: true,
+        properties: {
+          type: { type: "string", enum: NODE_TYPE_VALUES },
+          keyword: { type: "string" },
+          name: { type: "string" },
+          text: { type: "string" },
+          bounds: {
+            type: "object",
+            additionalProperties: false,
+            properties: {
+              x: { type: "number" },
+              y: { type: "number" },
+              width: { type: "number" },
+              height: { type: "number" },
+              minX: { type: "number" },
+              minY: { type: "number" },
+              maxX: { type: "number" },
+              maxY: { type: "number" },
+            },
+          },
+        },
+      },
+    }),
+    async run(input) {
+      const args = asRecord(input);
+      const project = await loadProject(readString(args, "projectRoot"));
+      return {
+        nodes: filterNodes(project.snapshot.nodes, args.filter).map(toNodeDto),
+      };
+    },
+  }),
+  tool({
+    name: "canvas.get_node",
+    description: "Read compact details for one board node from local project files.",
+    inputSchema: objectSchema({
+      projectRoot: stringSchema(PROJECT_ROOT_DESCRIPTION),
+      nodeId: stringSchema("Node id"),
+    }, ["projectRoot", "nodeId"]),
+    async run(input) {
+      const args = asRecord(input);
+      const project = await loadProject(readString(args, "projectRoot"));
+      return {
+        node: toNodeDto(getNodeOrThrow(project.snapshot, args.nodeId)),
+      };
+    },
+  }),
+  tool({
+    name: "canvas.create_nodes",
+    description: "Ask the running desktop app to create asset-driven BoardNode entries from local files, then save through desktop logic. Pass a file path unless kind is generating. Write text, markdown, or html content to a source file first and pass that path. Do not provide x/y; the desktop canvas chooses placement and returns the created node coordinates.",
+    inputSchema: objectSchema({
+      projectRoot: stringSchema(PROJECT_ROOT_DESCRIPTION),
+      nodes: {
+        type: "array",
+        minItems: 1,
+        items: {
+          type: "object",
+          additionalProperties: true,
+          properties: {
+            path: { type: "string" },
+            kind: {
+              type: "string",
+              description: "Optional compatibility hint. Use generating to create a lightweight placeholder without a path; otherwise the desktop importer determines the actual asset kind from the file.",
+              enum: ASSET_KIND_VALUES,
+            },
+            width: { type: "number" },
+            height: { type: "number" },
+            options: {
+              type: "object",
+              description: "Renderer parameters only. Do not put text, markdown, or html document content here.",
+              additionalProperties: true,
+            },
+            name: { type: "string" },
+          },
+        },
+      },
+    }, ["projectRoot", "nodes"]),
+    async run(input) {
+      const args = asRecord(input);
+      const command: McpWriteCommand = {
+        kind: "create_nodes",
+        projectRoot: readString(args, "projectRoot"),
+        nodes: readCreateNodes(args.nodes),
+      };
+      const result = await sendWriteCommand(command);
+      const project = await loadProject(command.projectRoot);
+      return {
+        nodes: result.nodes.map(toNodeDto),
+        assets: (result.assets ?? []).map((asset) => toAssetDto(project.root, asset)),
+      };
+    },
+  }),
+  tool({
+    name: "canvas.generating_node_install",
+    description: "Replace an existing generating placeholder node with a real local file asset. The desktop app imports the file, updates the node type/asset/name, and resizes the node to the real asset dimensions.",
+    inputSchema: objectSchema({
+      projectRoot: stringSchema(PROJECT_ROOT_DESCRIPTION),
+      nodeId: stringSchema("Generating board node id"),
+      path: stringSchema("Local file path to install into the generating node"),
+    }, ["projectRoot", "nodeId", "path"]),
+    async run(input) {
+      const args = asRecord(input);
+      const command: McpWriteCommand = {
+        kind: "generating_node_install",
+        projectRoot: readString(args, "projectRoot"),
+        nodeId: readString(args, "nodeId"),
+        path: readString(args, "path"),
+      };
+      const result = await sendWriteCommand(command);
+      const project = await loadProject(command.projectRoot);
+      return {
+        nodes: result.nodes.map(toNodeDto),
+        assets: (result.assets ?? []).map((asset) => toAssetDto(project.root, asset)),
+      };
+    },
+  }),
+  tool({
+    name: "canvas.update_nodes",
+    description: "Ask the running desktop app to merge node geometry, name, and node option updates, then save through desktop logic. Do not send text, markdown, or html content here; edit the source file for content changes.",
+    inputSchema: objectSchema({
+      projectRoot: stringSchema(PROJECT_ROOT_DESCRIPTION),
+      updates: {
+        type: "array",
+        minItems: 1,
+        items: {
+          type: "object",
+          additionalProperties: true,
+          required: ["id"],
+          properties: {
+            id: { type: "string" },
+            name: { type: "string" },
+            options: {
+              type: "object",
+              description: "Renderer parameters only. Do not put text, markdown, or html document content here.",
+              additionalProperties: true,
+            },
+            x: { type: "number" },
+            y: { type: "number" },
+            width: { type: "number" },
+            height: { type: "number" },
+            rotation: { type: "number" },
+            zIndex: { type: "number" },
+            locked: { type: "boolean" },
+          },
+        },
+      },
+    }, ["projectRoot", "updates"]),
+    async run(input) {
+      const args = asRecord(input);
+      const command: McpWriteCommand = {
+        kind: "update_nodes",
+        projectRoot: readString(args, "projectRoot"),
+        updates: readUpdates(args.updates),
+      };
+      const result = await sendWriteCommand(command);
+      return {
+        nodes: result.nodes.map(toNodeDto),
+      };
+    },
+  }),
+  tool({
+    name: "canvas.update_assets",
+    description: "Ask the running desktop app to replace asset metadata and media dimensions, then save through desktop logic. Do not use this to write text, markdown, or html content; edit the source file instead.",
+    inputSchema: objectSchema({
+      projectRoot: stringSchema(PROJECT_ROOT_DESCRIPTION),
+      assets: {
+        type: "array",
+        minItems: 1,
+        items: {
+          type: "object",
+          additionalProperties: true,
+          required: ["id"],
+          properties: {
+            id: { type: "string" },
+            metadata: { type: "object", additionalProperties: true },
+            width: { type: "number" },
+            height: { type: "number" },
+            duration: { type: "number" },
+            format: {
+              type: "string",
+              enum: MODEL_FORMAT_VALUES,
+            },
+          },
+        },
+      },
+    }, ["projectRoot", "assets"]),
+    async run(input) {
+      const args = asRecord(input);
+      const command: McpWriteCommand = {
+        kind: "update_assets",
+        projectRoot: readString(args, "projectRoot"),
+        assets: readAssetUpdates(args.assets),
+      };
+      const result = await sendWriteCommand(command);
+      const project = await loadProject(command.projectRoot);
+      return {
+        assets: (result.assets ?? []).map((asset) => toAssetDto(project.root, asset)),
+      };
+    },
+  }),
+  tool({
+    name: "canvas.refresh_node_preview",
+    description: "Ask the running desktop app to regenerate a text, markdown, or html node preview from its source file using the node's current bounds.",
+    inputSchema: objectSchema({
+      projectRoot: stringSchema(PROJECT_ROOT_DESCRIPTION),
+      nodeId: stringSchema("Text, markdown, or html board node id"),
+    }, ["projectRoot", "nodeId"]),
+    async run(input) {
+      const args = asRecord(input);
+      const command: McpWriteCommand = {
+        kind: "refresh_node_preview",
+        projectRoot: readString(args, "projectRoot"),
+        nodeId: readString(args, "nodeId"),
+      };
+      const result = await sendWriteCommand(command);
+      const project = await loadProject(command.projectRoot);
+      return {
+        nodes: result.nodes.map(toNodeDto),
+        assets: (result.assets ?? []).map((asset) => toAssetDto(project.root, asset)),
+      };
+    },
+  }),
+  tool({
+    name: "canvas.get_origin_asset_by_node",
+    description: "Return original asset information for a file-backed board node.",
+    inputSchema: objectSchema({
+      projectRoot: stringSchema(PROJECT_ROOT_DESCRIPTION),
+      nodeId: stringSchema("Board node id"),
+    }, ["projectRoot", "nodeId"]),
+    async run(input) {
+      const args = asRecord(input);
+      const project = await loadProject(readString(args, "projectRoot"));
+      const node = getNodeOrThrow(project.snapshot, args.nodeId);
+      const asset = getOriginAssetForNode(project.snapshot, args.nodeId);
+      return {
+        node: toNodeDto(node),
+        asset: {
+          ...toAssetDto(project.root, asset),
+          accessibleUrl: asset.webLink ?? asset.sourceUrl ?? null,
+        },
+      };
+    },
+  }),
+  tool({
+    name: "canvas.get_asset",
+    description: "Return compact asset details including original, derivatives, and metadata.",
+    inputSchema: objectSchema({
+      projectRoot: stringSchema(PROJECT_ROOT_DESCRIPTION),
+      assetId: stringSchema("Asset id"),
+    }, ["projectRoot", "assetId"]),
+    async run(input) {
+      const args = asRecord(input);
+      const project = await loadProject(readString(args, "projectRoot"));
+      return {
+        asset: toAssetDto(project.root, getAssetOrThrow(project.snapshot, args.assetId)),
+      };
+    },
+  }),
+  tool({
+    name: "canvas.read_project_info",
+    description: "Read compact project info, counts, viewport, and update timestamps.",
+    inputSchema: objectSchema({
+      projectRoot: stringSchema(PROJECT_ROOT_DESCRIPTION),
+    }),
+    async run(input) {
+      const project = await loadProject(readString(input, "projectRoot"));
+      return {
+        projectRoot: project.root,
+        boardPath: project.boardPath,
+        assetsPath: project.assetsPath,
+        nodeCount: project.snapshot.nodes.length,
+        assetCount: project.snapshot.assets.length,
+        viewport: project.snapshot.viewport ?? null,
+        updatedAt: Math.max(project.boardUpdatedAt ?? 0, project.assetsUpdatedAt ?? 0),
+        boardUpdatedAt: project.boardUpdatedAt,
+        assetsUpdatedAt: project.assetsUpdatedAt,
+      };
+    },
+  }),
+];
+
+function tool(definition: Omit<BoardTool, "kind" | "outputSchema"> & { outputSchema?: JSONSchema }): BoardTool {
+  return {
+    kind: "builtin",
+    outputSchema: definition.outputSchema ?? anyOutputSchema,
+    ...definition,
+  };
+}
+
+function objectSchema(properties: Record<string, unknown>, required = ["projectRoot"]) {
+  return {
+    type: "object",
+    additionalProperties: false,
+    required,
+    properties,
+  };
+}
+
+function stringSchema(description: string) {
+  return { type: "string", description };
+}
+
+function readCreateNodes(value: unknown): McpCreateNodeInput[] {
+  if (!Array.isArray(value) || value.length === 0) {
+    throw new BoardToolUserError("nodes must be a non-empty array");
+  }
+  return value.map((entry, index) => {
+    const node = asRecord(entry, `nodes[${index}]`);
+    if (node.x !== undefined || node.y !== undefined) {
+      throw new BoardToolUserError(`nodes[${index}].x/y is not supported; the desktop canvas chooses placement`);
+    }
+    if (node.kind !== undefined && !isAssetKind(node.kind)) {
+      throw new BoardToolUserError(`nodes[${index}].kind must be one of ${ASSET_KIND_VALUES.join(", ")}`);
+    }
+    const kind = node.kind;
+    const hasPath = typeof node.path === "string" && node.path.trim() !== "";
+    if (kind === "generating") {
+      if (node.path !== undefined && !hasPath) {
+        throw new BoardToolUserError(`nodes[${index}].path must be a non-empty string when provided`);
+      }
+    } else if (!hasPath) {
+      throw new BoardToolUserError(`nodes[${index}].path must be a non-empty string unless kind is generating`);
+    }
+    if (node.metadata !== undefined) {
+      throw new BoardToolUserError(`nodes[${index}].metadata is not supported; write content to a source file and pass path`);
+    }
+    if (node.text !== undefined) {
+      throw new BoardToolUserError(`nodes[${index}].text is not supported; write content to a source file and pass path`);
+    }
+    if (node.options !== undefined) {
+      asRecord(node.options, `nodes[${index}].options`);
+    }
+    return node as McpCreateNodeInput;
+  });
+}
+
+function isAssetKind(value: unknown): value is NonNullable<McpCreateNodeInput["kind"]> {
+  return typeof value === "string" && ASSET_KIND_VALUES.includes(value as NonNullable<McpCreateNodeInput["kind"]>);
+}
+
+function readAssetUpdates(value: unknown): McpUpdateAssetInput[] {
+  if (!Array.isArray(value) || value.length === 0) {
+    throw new BoardToolUserError("assets must be a non-empty array");
+  }
+  return value.map((entry, index) => {
+    const update = asRecord(entry, `assets[${index}]`);
+    readString(update, "id");
+    readOptionalNumber(update, "width", `assets[${index}]`);
+    readOptionalNumber(update, "height", `assets[${index}]`);
+    readOptionalNumber(update, "duration", `assets[${index}]`);
+    if (update.format !== undefined && !MODEL_FORMAT_VALUES.includes(update.format as ModelAssetFormat)) {
+      throw new BoardToolUserError(`assets[${index}].format must be a supported model format`);
+    }
+    if (update.metadata !== undefined) {
+      const metadata = asRecord(update.metadata, `assets[${index}].metadata`);
+      assertNoContentMetadata(metadata, `assets[${index}].metadata`);
+    }
+    return update as McpUpdateAssetInput;
+  });
+}
+
+function assertNoContentMetadata(metadata: Record<string, unknown>, label: string): void {
+  for (const key of ["html", "markdown", "text", "content"]) {
+    if (metadata[key] !== undefined) {
+      throw new BoardToolUserError(`${label}.${key} is not supported; edit the source file instead`);
+    }
+  }
+}
+
+function readUpdates(value: unknown): McpUpdateNodeInput[] {
+  if (!Array.isArray(value) || value.length === 0) {
+    throw new BoardToolUserError("updates must be a non-empty array");
+  }
+  return value.map((entry, index) => {
+    const update = asRecord(entry, `updates[${index}]`);
+    readString(update, "id");
+    if ("text" in update) {
+      throw new BoardToolUserError(`updates[${index}].text is not supported; edit the source file instead`);
+    }
+    readOptionalNumber(update, "x", `updates[${index}]`);
+    readOptionalNumber(update, "y", `updates[${index}]`);
+    readOptionalNumber(update, "width", `updates[${index}]`);
+    readOptionalNumber(update, "height", `updates[${index}]`);
+    readOptionalNumber(update, "rotation", `updates[${index}]`);
+    readOptionalNumber(update, "zIndex", `updates[${index}]`);
+    if (update.options !== undefined) {
+      asRecord(update.options, `updates[${index}].options`);
+    }
+    return update as McpUpdateNodeInput;
+  });
+}
+
+function readString(input: unknown, key: string): string {
+  const record = asRecord(input);
+  const value = record[key];
+  if (typeof value !== "string" || value.trim() === "") {
+    throw new BoardToolUserError(`${key} must be a non-empty string`);
+  }
+  return value;
+}
+
+function readOptionalNumber(input: Record<string, unknown>, key: string, label: string): void {
+  const value = input[key];
+  if (value !== undefined && (typeof value !== "number" || !Number.isFinite(value))) {
+    throw new BoardToolUserError(`${label}.${key} must be a finite number`);
+  }
+}
+
+function asRecord(input: unknown, label = "input"): Record<string, unknown> {
+  if (!input || typeof input !== "object" || Array.isArray(input)) {
+    throw new BoardToolUserError(`${label} must be an object`);
+  }
+  return input as Record<string, unknown>;
+}