@llc3233149/core 0.9.0

package/src/tools/registry.ts

@@ -0,0 +1,155 @@
+import type { ToolDef } from './schema'
+
+import {
+  getSelection, getPageTree, getNode, findNodes, queryNodes, getComponents,
+  listPages, switchPage, getCurrentPage, pageBounds, selectNodes, listFonts,
+  getJsx, diffJsx, designOverview, describeScreen
+} from './read'
+import {
+  createShape, render, createComponent, createInstance,
+  createPage, createVector, createSlice
+} from './create'
+import {
+  setFill, setStroke, setEffects, updateNode, setLayout, setConstraints,
+  setRotation, setOpacity, setRadius, setMinMax, setText, setFont, setFontRange,
+  setTextResize, setVisible, setBlend, setLocked, setStrokeAlign,
+  setTextProperties, setLayoutChild, setImageFill
+} from './modify'
+import {
+  deleteNode, cloneNode, renameNode, reparentNode, groupNodes, ungroupNode,
+  flattenNodes, nodeToComponent, nodeBounds, nodeMove, nodeResize,
+  nodeAncestors, nodeChildren, nodeTree, nodeBindings, nodeReplaceWith, arrangeNodes
+} from './structure'
+import {
+  listVariables, listCollections, getVariable, findVariables,
+  createVariable, setVariable, deleteVariable, bindVariable,
+  getCollection, createCollection, deleteCollection
+} from './variables'
+import {
+  booleanUnion, booleanSubtract, booleanIntersect, booleanExclude,
+  pathGet, pathSet, pathScale, pathFlip, pathMove,
+  viewportGet, viewportSet, viewportZoomToFit,
+  exportSvg, exportImage
+} from './vector'
+import {
+  analyzeColors, analyzeTypography, analyzeSpacing, analyzeClusters,
+  diffCreate, diffShow, evalCode,
+  snapshotDesignSystemTool, diffDesignSystem
+} from './analyze'
+import { exportTailwindConfig } from './export-tailwind-config'
+import { exportCode } from './export-code'
+import { describe } from './describe'
+import { getDesignPattern } from './patterns'
+import { createIcon } from './icons'
+
+export const ALL_TOOLS: ToolDef[] = [
+  // Read
+  getSelection,
+  getPageTree,
+  getNode,
+  findNodes,
+  queryNodes,
+  getComponents,
+  listPages,
+  switchPage,
+  getCurrentPage,
+  pageBounds,
+  selectNodes,
+  listFonts,
+  getJsx,
+  diffJsx,
+  designOverview,
+  describeScreen,
+  // Create
+  createShape,
+  render,
+  createComponent,
+  createInstance,
+  createPage,
+  createVector,
+  createSlice,
+  // Modify
+  setFill,
+  setStroke,
+  setEffects,
+  updateNode,
+  setLayout,
+  setConstraints,
+  setRotation,
+  setOpacity,
+  setRadius,
+  setMinMax,
+  setText,
+  setFont,
+  setFontRange,
+  setTextResize,
+  setVisible,
+  setBlend,
+  setLocked,
+  setStrokeAlign,
+  setTextProperties,
+  setLayoutChild,
+  setImageFill,
+  // Structure
+  deleteNode,
+  cloneNode,
+  renameNode,
+  reparentNode,
+  groupNodes,
+  ungroupNode,
+  flattenNodes,
+  nodeToComponent,
+  nodeBounds,
+  nodeMove,
+  nodeResize,
+  nodeAncestors,
+  nodeChildren,
+  nodeTree,
+  nodeBindings,
+  nodeReplaceWith,
+  arrangeNodes,
+  // Variables
+  listVariables,
+  listCollections,
+  getVariable,
+  findVariables,
+  createVariable,
+  setVariable,
+  deleteVariable,
+  bindVariable,
+  getCollection,
+  createCollection,
+  deleteCollection,
+  // Vector & export
+  booleanUnion,
+  booleanSubtract,
+  booleanIntersect,
+  booleanExclude,
+  pathGet,
+  pathSet,
+  pathScale,
+  pathFlip,
+  pathMove,
+  viewportGet,
+  viewportSet,
+  viewportZoomToFit,
+  exportSvg,
+  exportImage,
+  // Analyze & diff
+  analyzeColors,
+  analyzeTypography,
+  analyzeSpacing,
+  analyzeClusters,
+  diffCreate,
+  diffShow,
+  snapshotDesignSystemTool,
+  diffDesignSystem,
+  describe,
+  getDesignPattern,
+  createIcon,
+  // Export
+  exportTailwindConfig,
+  exportCode,
+  // Eval (dangerous: arbitrary code execution — consumers should gate on IS_DEV)
+  evalCode
+]

package/src/tools/schema.ts

@@ -0,0 +1,65 @@
+/**
+ * Tool definition schema.
+ *
+ * Each tool is defined once with typed params and an execute function
+ * that operates on FigmaAPI. Adapters for AI chat (valibot), CLI (citty),
+ * and MCP (JSON Schema) are generated from these definitions.
+ */
+
+import type { FigmaAPI, FigmaNodeProxy } from '../figma-api'
+
+export type ParamType = 'string' | 'number' | 'boolean' | 'color' | 'string[]'
+
+export interface ParamDef {
+  type: ParamType
+  description: string
+  required?: boolean
+  default?: unknown
+  enum?: string[]
+  min?: number
+  max?: number
+}
+
+export interface ToolDef {
+  name: string
+  description: string
+  mutates?: boolean
+  params: Record<string, ParamDef>
+  execute: (figma: FigmaAPI, args: Record<string, any>) => unknown
+}
+
+type ResolvedType<T extends ParamType> = T extends 'string'
+  ? string
+  : T extends 'number'
+    ? number
+    : T extends 'boolean'
+      ? boolean
+      : T extends 'color'
+        ? string
+        : T extends 'string[]'
+          ? string[]
+          : never
+
+type ResolvedParams<P extends Record<string, ParamDef>> = {
+  [K in keyof P as P[K]['required'] extends true ? K : never]: ResolvedType<P[K]['type']>
+} & {
+  [K in keyof P as P[K]['required'] extends true ? never : K]?: ResolvedType<P[K]['type']>
+}
+
+export function defineTool<P extends Record<string, ParamDef>>(def: {
+  name: string
+  description: string
+  mutates?: boolean
+  params: P
+  execute: (figma: FigmaAPI, args: ResolvedParams<P>) => unknown
+}): ToolDef {
+  return def as unknown as ToolDef
+}
+
+export function nodeToResult(node: FigmaNodeProxy): Record<string, unknown> {
+  return node.toJSON()
+}
+
+export function nodeSummary(node: FigmaNodeProxy): { id: string; name: string; type: string } {
+  return { id: node.id, name: node.name, type: node.type }
+}

package/src/tools/structure.ts

@@ -0,0 +1,348 @@
+import { defineTool, nodeSummary } from './schema'
+
+import type { FigmaNodeProxy } from '../figma-api'
+
+export const deleteNode = defineTool({
+  name: 'delete_node',
+  mutates: true,
+  description: 'Delete a node by ID.',
+  params: {
+    id: { type: 'string', description: 'Node ID to delete', required: true }
+  },
+  execute: (figma, { id }) => {
+    const node = figma.getNodeById(id)
+    if (!node) return { error: `Node "${id}" not found` }
+    node.remove()
+    return { deleted: id }
+  }
+})
+
+export const cloneNode = defineTool({
+  name: 'clone_node',
+  mutates: true,
+  description: 'Clone (duplicate) a node.',
+  params: {
+    id: { type: 'string', description: 'Node ID to clone', required: true }
+  },
+  execute: (figma, { id }) => {
+    const node = figma.getNodeById(id)
+    if (!node) return { error: `Node "${id}" not found` }
+    const clone = node.clone()
+    return nodeSummary(clone)
+  }
+})
+
+export const renameNode = defineTool({
+  name: 'rename_node',
+  mutates: true,
+  description: 'Rename a node in the layers panel.',
+  params: {
+    id: { type: 'string', description: 'Node ID', required: true },
+    name: { type: 'string', description: 'New name', required: true }
+  },
+  execute: (figma, { id, name }) => {
+    const node = figma.getNodeById(id)
+    if (!node) return { error: `Node "${id}" not found` }
+    node.name = name
+    return { id, name }
+  }
+})
+
+export const reparentNode = defineTool({
+  name: 'reparent_node',
+  mutates: true,
+  description: 'Move a node into a different parent.',
+  params: {
+    id: { type: 'string', description: 'Node ID to move', required: true },
+    parent_id: { type: 'string', description: 'New parent node ID', required: true }
+  },
+  execute: (figma, { id, parent_id }) => {
+    const node = figma.getNodeById(id)
+    const parent = figma.getNodeById(parent_id)
+    if (!node) return { error: `Node "${id}" not found` }
+    if (!parent) return { error: `Parent "${parent_id}" not found` }
+    parent.appendChild(node)
+    return { id, parent_id }
+  }
+})
+
+export const groupNodes = defineTool({
+  name: 'group_nodes',
+  mutates: true,
+  description: 'Group selected nodes.',
+  params: {
+    ids: { type: 'string[]', description: 'Node IDs to group', required: true }
+  },
+  execute: (figma, { ids }) => {
+    const nodes = ids
+      .map((id) => figma.getNodeById(id))
+      .filter((n): n is FigmaNodeProxy => n !== null)
+    if (nodes.length < 2) return { error: 'Need at least 2 nodes to group' }
+    const parent = nodes[0].parent ?? figma.currentPage
+    const group = figma.group(nodes, parent)
+    return nodeSummary(group)
+  }
+})
+
+export const ungroupNode = defineTool({
+  name: 'ungroup_node',
+  mutates: true,
+  description: 'Ungroup a group node.',
+  params: {
+    id: { type: 'string', description: 'Group node ID', required: true }
+  },
+  execute: (figma, { id }) => {
+    const node = figma.getNodeById(id)
+    if (!node) return { error: `Node "${id}" not found` }
+    figma.ungroup(node)
+    return { ungrouped: id }
+  }
+})
+
+export const flattenNodes = defineTool({
+  name: 'flatten_nodes',
+  mutates: true,
+  description: 'Flatten nodes into a single vector.',
+  params: {
+    ids: { type: 'string[]', description: 'Node IDs to flatten', required: true }
+  },
+  execute: (figma, { ids }) => {
+    const result = figma.flattenNode(ids)
+    return nodeSummary(result)
+  }
+})
+
+export const nodeToComponent = defineTool({
+  name: 'node_to_component',
+  mutates: true,
+  description: 'Convert one or more frames/groups into components.',
+  params: {
+    ids: { type: 'string[]', description: 'Node IDs to convert', required: true }
+  },
+  execute: (figma, { ids }) => {
+    const results: { id: string; name: string; originalId: string }[] = []
+    for (const id of ids) {
+      const node = figma.getNodeById(id)
+      if (!node) continue
+      const comp = figma.createComponentFromNode(node)
+      results.push({ id: comp.id, name: comp.name, originalId: id })
+    }
+    return { converted: results }
+  }
+})
+
+export const nodeBounds = defineTool({
+  name: 'node_bounds',
+  description: 'Get absolute bounding box of a node.',
+  params: {
+    id: { type: 'string', description: 'Node ID', required: true }
+  },
+  execute: (figma, { id }) => {
+    const node = figma.getNodeById(id)
+    if (!node) return { error: `Node "${id}" not found` }
+    return { id, bounds: node.absoluteBoundingBox }
+  }
+})
+
+export const nodeMove = defineTool({
+  name: 'node_move',
+  mutates: true,
+  description: 'Move a node to new coordinates.',
+  params: {
+    id: { type: 'string', description: 'Node ID', required: true },
+    x: { type: 'number', description: 'X position', required: true },
+    y: { type: 'number', description: 'Y position', required: true }
+  },
+  execute: (figma, { id, x, y }) => {
+    const node = figma.getNodeById(id)
+    if (!node) return { error: `Node "${id}" not found` }
+    node.x = x
+    node.y = y
+    return { id, x, y }
+  }
+})
+
+export const nodeResize = defineTool({
+  name: 'node_resize',
+  mutates: true,
+  description: 'Resize a node.',
+  params: {
+    id: { type: 'string', description: 'Node ID', required: true },
+    width: { type: 'number', description: 'Width', required: true, min: 1 },
+    height: { type: 'number', description: 'Height', required: true, min: 1 }
+  },
+  execute: (figma, { id, width, height }) => {
+    const node = figma.getNodeById(id)
+    if (!node) return { error: `Node "${id}" not found` }
+    node.resize(width, height)
+    return { id, width, height }
+  }
+})
+
+export const nodeAncestors = defineTool({
+  name: 'node_ancestors',
+  description: 'Get the ancestor chain from a node to the page root.',
+  params: {
+    id: { type: 'string', description: 'Node ID', required: true },
+    depth: { type: 'number', description: 'Max depth to traverse' }
+  },
+  execute: (figma, args) => {
+    const node = figma.getNodeById(args.id)
+    if (!node) return { error: `Node "${args.id}" not found` }
+    const ancestors: { id: string; name: string; type: string }[] = []
+    let current = node.parent
+    let d = 0
+    while (current && (!args.depth || d < args.depth)) {
+      ancestors.push({ id: current.id, name: current.name, type: current.type })
+      current = current.parent
+      d++
+    }
+    return { id: args.id, ancestors }
+  }
+})
+
+export const nodeChildren = defineTool({
+  name: 'node_children',
+  description: 'Get direct children of a node.',
+  params: {
+    id: { type: 'string', description: 'Node ID', required: true }
+  },
+  execute: (figma, { id }) => {
+    const node = figma.getNodeById(id)
+    if (!node) return { error: `Node "${id}" not found` }
+    return {
+      id,
+      children: node.children.map((c) => ({ id: c.id, name: c.name, type: c.type }))
+    }
+  }
+})
+
+export const nodeTree = defineTool({
+  name: 'node_tree',
+  description: 'Get a node tree with types and hierarchy.',
+  params: {
+    id: { type: 'string', description: 'Node ID', required: true },
+    depth: { type: 'number', description: 'Max depth (default: unlimited)' }
+  },
+  execute: (figma, args) => {
+    const node = figma.getNodeById(args.id)
+    if (!node) return { error: `Node "${args.id}" not found` }
+    function buildTree(n: FigmaNodeProxy, d: number): Record<string, unknown> {
+      const result: Record<string, unknown> = { id: n.id, name: n.name, type: n.type }
+      if (args.depth === undefined || d < args.depth) {
+        const kids = n.children
+        if (kids.length > 0) result.children = kids.map((c) => buildTree(c, d + 1))
+      }
+      return result
+    }
+    return buildTree(node, 0)
+  }
+})
+
+export const nodeBindings = defineTool({
+  name: 'node_bindings',
+  description: 'Get variable bindings for a node.',
+  params: {
+    id: { type: 'string', description: 'Node ID', required: true }
+  },
+  execute: (figma, { id }) => {
+    const raw = figma.graph.getNode(id)
+    if (!raw) return { error: `Node "${id}" not found` }
+    return { id, bindings: raw.boundVariables }
+  }
+})
+
+export const nodeReplaceWith = defineTool({
+  name: 'node_replace_with',
+  mutates: true,
+  description: 'Replace a node with JSX content.',
+  params: {
+    id: { type: 'string', description: 'Node ID to replace', required: true },
+    jsx: { type: 'string', description: 'JSX string for the replacement', required: true }
+  },
+  execute: async (figma, args) => {
+    const node = figma.getNodeById(args.id)
+    if (!node) return { error: `Node "${args.id}" not found` }
+    const parentId = node.parent?.id ?? figma.currentPageId
+    const x = node.x
+    const y = node.y
+    node.remove()
+    const { renderJSX } = await import('../render/render-jsx.js')
+    const result = renderJSX(figma.graph, args.jsx, { parentId, x, y })
+    return { id: result.id, name: result.name, type: result.type }
+  }
+})
+
+export const arrangeNodes = defineTool({
+  name: 'arrange',
+  mutates: true,
+  description:
+    'Arrange top-level nodes on the canvas in a grid, row, or column layout. Useful after batch creation to tidy up overlapping frames.',
+  params: {
+    ids: { type: 'string[]', description: 'Node IDs to arrange (default: all top-level children)' },
+    mode: {
+      type: 'string',
+      description: 'Layout mode',
+      enum: ['grid', 'row', 'column'],
+      default: 'grid'
+    },
+    gap: { type: 'number', description: 'Spacing between nodes (default: 40)' },
+    cols: { type: 'number', description: 'Column count for grid mode (default: auto)' }
+  },
+  execute: (figma, args) => {
+    const gap = args.gap ?? 40
+    const mode = args.mode ?? 'grid'
+    const page = figma.currentPage
+
+    let nodes: FigmaNodeProxy[]
+    if (args.ids && args.ids.length > 0) {
+      nodes = args.ids
+        .map((id) => figma.getNodeById(id))
+        .filter((n): n is FigmaNodeProxy => n !== null)
+    } else {
+      nodes = [...page.children]
+    }
+
+    if (nodes.length === 0) return { error: 'No nodes to arrange' }
+    const first = nodes[0]
+
+    if (mode === 'row') {
+      let x = first.x
+      const y = first.y
+      for (const node of nodes) {
+        node.x = x
+        node.y = y
+        x += node.width + gap
+      }
+    } else if (mode === 'column') {
+      const x = first.x
+      let y = first.y
+      for (const node of nodes) {
+        node.x = x
+        node.y = y
+        y += node.height + gap
+      }
+    } else {
+      const cols = args.cols ?? Math.ceil(Math.sqrt(nodes.length))
+      const startX = first.x
+      let x = startX
+      let y = first.y
+      let rowHeight = 0
+
+      for (let i = 0; i < nodes.length; i++) {
+        const node = nodes[i]
+        if (i > 0 && i % cols === 0) {
+          x = startX
+          y += rowHeight + gap
+          rowHeight = 0
+        }
+        node.x = x
+        node.y = y
+        x += node.width + gap
+        rowHeight = Math.max(rowHeight, node.height)
+      }
+    }
+
+    return { arranged: nodes.length, mode }
+  }
+})