@pixi-board/board-plugin-canvas 0.1.0

package/src/projects.ts

@@ -0,0 +1,269 @@
+import type { ProjectInfo } from "@canvas/board-domain";
+import { promises as fs } from "node:fs";
+import net from "node:net";
+import os from "node:os";
+import path from "node:path";
+import { toProjectInfo } from "./dto";
+import { BoardToolUserError } from "./errors";
+
+const APP_IDENTIFIER = "com.codex.pixi-board";
+const ACTIVE_PROJECT = "active";
+const LAST_PROJECT_FILE = ".last-canvas";
+const KNOWN_PROJECTS_FILE = ".known-canvas-projects.json";
+const BRIDGE_FILE = ".canvas-mcp-bridge.json";
+const BRIDGE_CONNECT_TIMEOUT_MS = 250;
+
+type BridgeEndpoint = {
+  version: number;
+  host: string;
+  port: number;
+  token: string;
+  updatedAt: number;
+};
+
+export type KnownProject = ProjectInfo & {
+  bridgeAvailable: boolean;
+};
+
+type ProjectOptions = {
+  appRoot?: string;
+};
+
+export async function resolveProjectRoot(projectRoot: unknown, options?: ProjectOptions): Promise<string> {
+  if (typeof projectRoot !== "string" || projectRoot.trim() === "") {
+    throw new BoardToolUserError('projectRoot must be a non-empty string or "active"');
+  }
+
+  if (projectRoot.trim() === ACTIVE_PROJECT) {
+    return resolveActiveProjectRoot(options);
+  }
+
+  return realpathForProject(projectRoot);
+}
+
+export async function listKnownProjects(options?: ProjectOptions): Promise<KnownProject[]> {
+  const appRoot = resolveAppRoot(options);
+  const roots = await readKnownProjectRoots(appRoot);
+  roots.sort((left, right) => projectDisplayName(left).localeCompare(projectDisplayName(right), undefined, {
+    sensitivity: "accent",
+  }));
+
+  const bridgeAvailability = await Promise.all(
+    roots.map(async (root) => ({
+      root,
+      bridgeAvailable: await isBridgeAvailable(root),
+    })),
+  );
+
+  return bridgeAvailability.map(({ root, bridgeAvailable }) => ({
+    ...toProjectInfo(root),
+    bridgeAvailable,
+  }));
+}
+
+export async function resolveActiveProjectRoot(options?: ProjectOptions): Promise<string> {
+  const appRoot = resolveAppRoot(options);
+  const root = await readLastProject(appRoot);
+  if (!root) {
+    throw new BoardToolUserError("No active canvas project. Open a project in the desktop app first.");
+  }
+  return root;
+}
+
+async function readKnownProjectRoots(appRoot: string): Promise<string[]> {
+  const registryPath = path.join(appRoot, KNOWN_PROJECTS_FILE);
+  let parsed: unknown = [];
+  try {
+    parsed = JSON.parse(await fs.readFile(registryPath, "utf8"));
+  } catch (error) {
+    if (!isMissing(error)) {
+      await writeKnownProjectRoots(registryPath, []);
+    }
+    return [];
+  }
+
+  if (!Array.isArray(parsed)) {
+    await writeKnownProjectRoots(registryPath, []);
+    return [];
+  }
+
+  const validRoots: string[] = [];
+  for (const entry of parsed) {
+    if (typeof entry !== "string" || entry.trim() === "") continue;
+    try {
+      const root = await fs.realpath(entry);
+      if (await isCanvasProject(root)) {
+        validRoots.push(root);
+      }
+    } catch {
+      // Ignore stale project entries and lazily clean them below.
+    }
+  }
+
+  const dedupedRoots = dedupeProjectRoots(validRoots);
+  const rawRoots = parsed.filter((entry): entry is string => typeof entry === "string" && entry.trim() !== "");
+  if (!sameProjectLists(rawRoots, dedupedRoots)) {
+    await writeKnownProjectRoots(registryPath, dedupedRoots);
+  }
+
+  return dedupedRoots;
+}
+
+async function readLastProject(appRoot: string): Promise<string | null> {
+  const lastProjectPath = path.join(appRoot, LAST_PROJECT_FILE);
+  let stored: string;
+  try {
+    stored = await fs.readFile(lastProjectPath, "utf8");
+  } catch (error) {
+    if (isMissing(error)) return null;
+    throw error;
+  }
+
+  const candidate = stored.trim();
+  if (!candidate) return null;
+  try {
+    const root = await fs.realpath(candidate);
+    return (await isCanvasProject(root)) ? root : null;
+  } catch {
+    return null;
+  }
+}
+
+async function writeKnownProjectRoots(registryPath: string, roots: string[]): Promise<void> {
+  await fs.mkdir(path.dirname(registryPath), { recursive: true });
+  await fs.writeFile(`${registryPath}.tmp`, `${JSON.stringify(roots, null, 2)}\n`, "utf8");
+  await fs.rename(`${registryPath}.tmp`, registryPath);
+}
+
+async function isCanvasProject(projectRoot: string): Promise<boolean> {
+  try {
+    const [board, assets] = await Promise.all([
+      fs.stat(path.join(projectRoot, "board.json")),
+      fs.stat(path.join(projectRoot, "assets.json")),
+    ]);
+    return board.isFile() && assets.isFile();
+  } catch {
+    return false;
+  }
+}
+
+async function realpathForProject(projectRoot: string): Promise<string> {
+  try {
+    const root = await fs.realpath(projectRoot);
+    const stat = await fs.stat(root);
+    if (!stat.isDirectory()) {
+      throw new BoardToolUserError(`projectRoot is not a directory: ${projectRoot}`);
+    }
+    if (!(await isCanvasProject(root))) {
+      throw new BoardToolUserError(`invalid canvas project: ${projectRoot}`);
+    }
+    return root;
+  } catch (error) {
+    if (error instanceof BoardToolUserError) throw error;
+    throw new BoardToolUserError(`Cannot access projectRoot ${projectRoot}: ${String(error)}`);
+  }
+}
+
+async function isBridgeAvailable(projectRoot: string): Promise<boolean> {
+  const bridgePath = path.join(projectRoot, BRIDGE_FILE);
+  let value: unknown;
+  try {
+    value = JSON.parse(await fs.readFile(bridgePath, "utf8"));
+  } catch {
+    return false;
+  }
+  if (!isEndpoint(value)) return false;
+  return canConnectToBridge(value.host, value.port);
+}
+
+function canConnectToBridge(host: string, port: number): Promise<boolean> {
+  return new Promise((resolve) => {
+    const socket = net.createConnection({ host, port });
+    let settled = false;
+    const settle = (result: boolean) => {
+      if (settled) return;
+      settled = true;
+      socket.destroy();
+      resolve(result);
+    };
+    const timer = setTimeout(() => settle(false), BRIDGE_CONNECT_TIMEOUT_MS);
+
+    socket.once("connect", () => {
+      clearTimeout(timer);
+      settle(true);
+    });
+    socket.once("error", () => {
+      clearTimeout(timer);
+      settle(false);
+    });
+    socket.once("close", () => {
+      clearTimeout(timer);
+      settle(false);
+    });
+  });
+}
+
+function resolveAppRoot(options?: ProjectOptions): string {
+  if (options?.appRoot) {
+    return path.resolve(options.appRoot);
+  }
+
+  if (process.platform === "darwin") {
+    return path.join(os.homedir(), "Library", "Application Support", APP_IDENTIFIER);
+  }
+
+  if (process.platform === "win32") {
+    const appData = process.env.APPDATA;
+    if (!appData) {
+      throw new BoardToolUserError("APPDATA is not set; cannot resolve the desktop app project root");
+    }
+    return path.join(appData, APP_IDENTIFIER);
+  }
+
+  const baseDir = process.env.XDG_DATA_HOME ?? path.join(os.homedir(), ".local", "share");
+  return path.join(baseDir, APP_IDENTIFIER);
+}
+
+function dedupeProjectRoots(roots: string[]): string[] {
+  const seen = new Set<string>();
+  const deduped: string[] = [];
+  for (const root of roots) {
+    const key = normalizeRootKey(root);
+    if (seen.has(key)) continue;
+    seen.add(key);
+    deduped.push(root);
+  }
+  return deduped;
+}
+
+function sameProjectLists(left: string[], right: string[]): boolean {
+  if (left.length !== right.length) return false;
+  return left.every((value, index) => normalizeRootKey(value) === normalizeRootKey(right[index]));
+}
+
+function normalizeRootKey(root: string): string {
+  return process.platform === "win32" ? root.toLowerCase() : root;
+}
+
+function projectDisplayName(projectRoot: string): string {
+  return path.basename(projectRoot).toLowerCase();
+}
+
+function isMissing(error: unknown): boolean {
+  return Boolean(error && typeof error === "object" && "code" in error && error.code === "ENOENT");
+}
+
+function isEndpoint(value: unknown): value is BridgeEndpoint {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const endpoint = value as Partial<BridgeEndpoint>;
+  return (
+    endpoint.version === 1 &&
+    endpoint.host === "127.0.0.1" &&
+    typeof endpoint.port === "number" &&
+    Number.isInteger(endpoint.port) &&
+    endpoint.port > 0 &&
+    typeof endpoint.token === "string" &&
+    endpoint.token.length > 0 &&
+    typeof endpoint.updatedAt === "number"
+  );
+}

package/src/reader.ts

@@ -0,0 +1,177 @@
+import type { Asset, BoardNode, BoardSnapshot, BoardViewportSnapshot } from "@canvas/board-domain";
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { BoardToolUserError, errorMessage } from "./errors";
+import { resolveProjectRoot } from "./projects";
+
+type BoardFile = {
+  schemaVersion?: number;
+  updatedAt?: number;
+  viewport?: BoardViewportSnapshot | null;
+  nodes?: BoardNode[];
+};
+
+type AssetFile = {
+  schemaVersion?: number;
+  updatedAt?: number;
+  assets?: Asset[];
+};
+
+export type ProjectFiles = {
+  root: string;
+  boardPath: string;
+  assetsPath: string;
+};
+
+export type LoadedProject = ProjectFiles & {
+  boardUpdatedAt: number | null;
+  assetsUpdatedAt: number | null;
+  snapshot: BoardSnapshot;
+};
+
+export async function resolveProjectFiles(projectRoot: unknown): Promise<ProjectFiles> {
+  const root = await resolveProjectRoot(projectRoot);
+  const boardPath = path.join(root, "board.json");
+  const assetsPath = path.join(root, "assets.json");
+  await assertReadableFile(boardPath, "board.json");
+  await assertReadableFile(assetsPath, "assets.json");
+  return { root, boardPath, assetsPath };
+}
+
+export async function loadProject(projectRoot: unknown): Promise<LoadedProject> {
+  const files = await resolveProjectFiles(projectRoot);
+  const [boardResult, assetsResult] = await Promise.all([
+    readJsonFile(files.boardPath, "board.json"),
+    readJsonFile(files.assetsPath, "assets.json"),
+  ]);
+
+  const board = parseBoardFile(boardResult.value, files.boardPath);
+  const assets = parseAssetFile(assetsResult.value, files.assetsPath);
+  return {
+    ...files,
+    boardUpdatedAt: board.updatedAt ?? boardResult.mtimeMs,
+    assetsUpdatedAt: assets.updatedAt ?? assetsResult.mtimeMs,
+    snapshot: {
+      nodes: board.nodes,
+      assets: assets.assets,
+      viewport: board.viewport ?? null,
+    },
+  };
+}
+
+export function getNodeOrThrow(snapshot: BoardSnapshot, nodeId: unknown): BoardNode {
+  if (typeof nodeId !== "string" || nodeId.trim() === "") {
+    throw new BoardToolUserError("nodeId must be a non-empty string");
+  }
+  const node = snapshot.nodes.find((entry) => entry.id === nodeId);
+  if (!node) {
+    throw new BoardToolUserError(`Node not found: ${nodeId}`);
+  }
+  return node;
+}
+
+export function getAssetOrThrow(snapshot: BoardSnapshot, assetId: unknown): Asset {
+  if (typeof assetId !== "string" || assetId.trim() === "") {
+    throw new BoardToolUserError("assetId must be a non-empty string");
+  }
+  const asset = snapshot.assets.find((entry) => entry.id === assetId);
+  if (!asset) {
+    throw new BoardToolUserError(`Asset not found: ${assetId}`);
+  }
+  return asset;
+}
+
+export function getOriginAssetForNode(snapshot: BoardSnapshot, nodeId: unknown): Asset {
+  const node = getNodeOrThrow(snapshot, nodeId);
+  const asset = getAssetOrThrow(snapshot, node.assetId);
+  if (!asset.localPath) {
+    throw new BoardToolUserError(`Asset has no original file: ${asset.id}`);
+  }
+  return asset;
+}
+
+async function assertReadableFile(filePath: string, label: string): Promise<void> {
+  try {
+    const stat = await fs.stat(filePath);
+    if (!stat.isFile()) {
+      throw new BoardToolUserError(`${label} is not a file: ${filePath}`);
+    }
+  } catch (error) {
+    if (error instanceof BoardToolUserError) throw error;
+    throw new BoardToolUserError(`Cannot read ${label} at ${filePath}: ${errorMessage(error)}`);
+  }
+}
+
+async function readJsonFile(filePath: string, label: string): Promise<{ value: unknown; mtimeMs: number }> {
+  let text: string;
+  let mtimeMs = 0;
+  try {
+    const [content, stat] = await Promise.all([fs.readFile(filePath, "utf8"), fs.stat(filePath)]);
+    text = content;
+    mtimeMs = Math.trunc(stat.mtimeMs);
+  } catch (error) {
+    throw new BoardToolUserError(`Failed to read ${label} at ${filePath}: ${errorMessage(error)}`);
+  }
+
+  try {
+    return { value: JSON.parse(text), mtimeMs };
+  } catch (error) {
+    throw new BoardToolUserError(
+      `Failed to parse ${label} at ${filePath}: ${errorMessage(error)}. The file may be mid-write; retry the read.`,
+    );
+  }
+}
+
+function parseBoardFile(value: unknown, filePath: string): Required<Pick<BoardFile, "nodes">> & BoardFile {
+  if (!isRecord(value)) {
+    throw new BoardToolUserError(`Invalid board.json at ${filePath}: expected an object`);
+  }
+  if (!Array.isArray(value.nodes)) {
+    throw new BoardToolUserError(`Invalid board.json at ${filePath}: missing nodes array`);
+  }
+  return {
+    schemaVersion: numberOrUndefined(value.schemaVersion),
+    updatedAt: numberOrUndefined(value.updatedAt),
+    viewport: parseViewport(value.viewport),
+    nodes: value.nodes as BoardNode[],
+  };
+}
+
+function parseAssetFile(value: unknown, filePath: string): Required<Pick<AssetFile, "assets">> & AssetFile {
+  if (!isRecord(value)) {
+    throw new BoardToolUserError(`Invalid assets.json at ${filePath}: expected an object`);
+  }
+  if (!Array.isArray(value.assets)) {
+    throw new BoardToolUserError(`Invalid assets.json at ${filePath}: missing assets array`);
+  }
+  return {
+    schemaVersion: numberOrUndefined(value.schemaVersion),
+    updatedAt: numberOrUndefined(value.updatedAt),
+    assets: value.assets as Asset[],
+  };
+}
+
+function parseViewport(value: unknown): BoardViewportSnapshot | null {
+  if (value === null || value === undefined) return null;
+  if (!isRecord(value) || typeof value.scale !== "number" || !isRecord(value.offset)) {
+    return null;
+  }
+  if (typeof value.offset.x !== "number" || typeof value.offset.y !== "number") {
+    return null;
+  }
+  return {
+    scale: value.scale,
+    offset: {
+      x: value.offset.x,
+      y: value.offset.y,
+    },
+  };
+}
+
+function numberOrUndefined(value: unknown): number | undefined {
+  return typeof value === "number" ? value : undefined;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/src/writerClient.ts

@@ -0,0 +1,141 @@
+import type { McpWriteCommand, McpWriteCommandResult } from "@canvas/board-domain";
+import { promises as fs } from "node:fs";
+import net from "node:net";
+import path from "node:path";
+import { BoardToolUserError, errorMessage } from "./errors";
+import { resolveProjectFiles } from "./reader";
+
+type BridgeEndpoint = {
+  version: 1;
+  host: string;
+  port: number;
+  token: string;
+  updatedAt: number;
+};
+
+type BridgeResponse =
+  | { ok: true; data: McpWriteCommandResult }
+  | { ok: false; error: string };
+
+const BRIDGE_FILE = ".canvas-mcp-bridge.json";
+const CONNECT_TIMEOUT_MS = 1_500;
+const RESPONSE_TIMEOUT_MS = 30_000;
+
+export async function sendWriteCommand(command: McpWriteCommand): Promise<McpWriteCommandResult> {
+  const files = await resolveProjectFiles(command.projectRoot);
+  const endpoint = await readBridgeEndpoint(files.root);
+  const response = await sendJsonLine(endpoint, {
+    token: endpoint.token,
+    request: {
+      ...command,
+      projectRoot: files.root,
+    },
+  });
+  if (!response.ok) {
+    throw new BoardToolUserError(response.error);
+  }
+  return response.data;
+}
+
+async function readBridgeEndpoint(projectRoot: string): Promise<BridgeEndpoint> {
+  const bridgePath = path.join(projectRoot, BRIDGE_FILE);
+  let value: unknown;
+  try {
+    value = JSON.parse(await fs.readFile(bridgePath, "utf8"));
+  } catch (error) {
+    throw new BoardToolUserError(
+      `Desktop app is not available for writes: cannot read ${BRIDGE_FILE} in ${projectRoot}. Start the desktop app and open this project. Details: ${errorMessage(error)}`,
+    );
+  }
+  if (!isEndpoint(value)) {
+    throw new BoardToolUserError(`Desktop app bridge file is invalid: ${bridgePath}`);
+  }
+  return value;
+}
+
+function sendJsonLine(endpoint: BridgeEndpoint, payload: unknown): Promise<BridgeResponse> {
+  return new Promise((resolve, reject) => {
+    const socket = net.createConnection({ host: endpoint.host, port: endpoint.port });
+    let buffer = "";
+    let settled = false;
+    const connectTimer = setTimeout(() => {
+      socket.destroy();
+      reject(new BoardToolUserError("Desktop app is not available for writes: bridge connection timed out"));
+    }, CONNECT_TIMEOUT_MS);
+    const responseTimer = setTimeout(() => {
+      socket.destroy();
+      reject(new BoardToolUserError("Desktop app did not finish the write command before the timeout"));
+    }, RESPONSE_TIMEOUT_MS);
+
+    const settle = (fn: () => void) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(connectTimer);
+      clearTimeout(responseTimer);
+      fn();
+    };
+
+    socket.setEncoding("utf8");
+    socket.on("connect", () => {
+      clearTimeout(connectTimer);
+      socket.write(`${JSON.stringify(payload)}\n`);
+    });
+    socket.on("data", (chunk) => {
+      buffer += chunk;
+      const newline = buffer.indexOf("\n");
+      if (newline < 0) return;
+      const line = buffer.slice(0, newline);
+      settle(() => {
+        socket.end();
+        try {
+          const parsed = JSON.parse(line);
+          if (isBridgeResponse(parsed)) {
+            resolve(parsed);
+          } else {
+            reject(new BoardToolUserError("Desktop app returned an invalid bridge response"));
+          }
+        } catch (error) {
+          reject(new BoardToolUserError(`Desktop app returned invalid JSON: ${errorMessage(error)}`));
+        }
+      });
+    });
+    socket.on("error", (error) => {
+      settle(() => {
+        reject(
+          new BoardToolUserError(
+            `Desktop app is not available for writes: failed to connect to bridge ${endpoint.host}:${endpoint.port}. Details: ${error.message}`,
+          ),
+        );
+      });
+    });
+    socket.on("close", () => {
+      if (settled) return;
+      settle(() => {
+        reject(new BoardToolUserError("Desktop app bridge closed before returning a write result"));
+      });
+    });
+  });
+}
+
+function isEndpoint(value: unknown): value is BridgeEndpoint {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const endpoint = value as Partial<BridgeEndpoint>;
+  return (
+    endpoint.version === 1 &&
+    endpoint.host === "127.0.0.1" &&
+    typeof endpoint.port === "number" &&
+    Number.isInteger(endpoint.port) &&
+    endpoint.port > 0 &&
+    typeof endpoint.token === "string" &&
+    endpoint.token.length > 0 &&
+    typeof endpoint.updatedAt === "number"
+  );
+}
+
+function isBridgeResponse(value: unknown): value is BridgeResponse {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const response = value as Partial<BridgeResponse>;
+  if (response.ok === true) return typeof response.data === "object" && response.data !== null;
+  if (response.ok === false) return typeof response.error === "string";
+  return false;
+}