@open-pencil/cli 0.1.0

package/src/commands/eval.ts

@@ -0,0 +1,78 @@
+import { defineCommand } from 'citty'
+
+import { FigmaAPI } from '@open-pencil/core'
+
+import { loadDocument } from '../headless'
+import { printError } from '../format'
+
+function serializeResult(value: unknown): unknown {
+  if (value === undefined || value === null) return value
+  if (typeof value === 'object' && value !== null && 'toJSON' in value && typeof value.toJSON === 'function') {
+    return value.toJSON()
+  }
+  if (Array.isArray(value)) return value.map(serializeResult)
+  return value
+}
+
+export default defineCommand({
+  meta: { description: 'Execute JavaScript with Figma plugin API' },
+  args: {
+    file: { type: 'positional', description: '.fig file path', required: true },
+    code: { type: 'string', alias: 'c', description: 'JavaScript code to execute' },
+    stdin: { type: 'boolean', description: 'Read code from stdin' },
+    write: { type: 'boolean', alias: 'w', description: 'Write changes back to the input file' },
+    output: { type: 'string', alias: 'o', description: 'Write to a different file' },
+    json: { type: 'boolean', description: 'Output as JSON' },
+    quiet: { type: 'boolean', alias: 'q', description: 'Suppress output' },
+  },
+  async run({ args }) {
+    let code = args.code
+
+    if (args.stdin) {
+      const chunks: Buffer[] = []
+      for await (const chunk of process.stdin) chunks.push(chunk as Buffer)
+      code = Buffer.concat(chunks).toString('utf-8')
+    }
+
+    if (!code) {
+      printError('Provide code via --code or --stdin')
+      process.exit(1)
+    }
+
+    const graph = await loadDocument(args.file)
+    const figma = new FigmaAPI(graph)
+
+    const AsyncFunction = Object.getPrototypeOf(async function () {}).constructor
+    const wrappedCode = code.trim().startsWith('return')
+      ? code
+      : `return (async () => { ${code} })()`
+
+    let result: unknown
+    try {
+      const fn = new AsyncFunction('figma', wrappedCode)
+      result = await fn(figma)
+    } catch (err) {
+      printError(err instanceof Error ? err.message : String(err))
+      process.exit(1)
+    }
+
+    if (!args.quiet && result !== undefined) {
+      const serialized = serializeResult(result)
+      if (args.json || !process.stdout.isTTY) {
+        console.log(JSON.stringify(serialized, null, 2))
+      } else {
+        console.log(serialized)
+      }
+    }
+
+    if (args.write || args.output) {
+      const { exportFigFile } = await import('@open-pencil/core')
+      const outPath = args.output ?? args.file
+      const data = exportFigFile(graph)
+      await Bun.write(outPath, data)
+      if (!args.quiet) {
+        console.error(`Written to ${outPath}`)
+      }
+    }
+  },
+})

package/src/commands/export.ts

@@ -0,0 +1,67 @@
+import { defineCommand } from 'citty'
+import { basename, extname, resolve } from 'node:path'
+
+import { loadDocument, loadFonts, exportNodes, exportThumbnail } from '../headless'
+import { ok, printError } from '../format'
+import type { ExportFormat } from '@open-pencil/core'
+
+export default defineCommand({
+  meta: { description: 'Export a .fig file to PNG, JPG, or WEBP' },
+  args: {
+    file: { type: 'positional', description: '.fig file path', required: true },
+    output: { type: 'string', alias: 'o', description: 'Output file path (default: <name>.<format>)' },
+    format: { type: 'string', alias: 'f', description: 'Export format: png, jpg, webp (default: png)', default: 'png' },
+    scale: { type: 'string', alias: 's', description: 'Export scale (default: 1)', default: '1' },
+    quality: { type: 'string', alias: 'q', description: 'Quality 0-100 for JPG/WEBP (default: 90)' },
+    page: { type: 'string', description: 'Page name (default: first page)' },
+    node: { type: 'string', description: 'Node ID to export (default: all top-level nodes)' },
+    thumbnail: { type: 'boolean', description: 'Export page thumbnail instead of full render' },
+    width: { type: 'string', description: 'Thumbnail width (default: 1920)', default: '1920' },
+    height: { type: 'string', description: 'Thumbnail height (default: 1080)', default: '1080' }
+  },
+  async run({ args }) {
+    const format = args.format.toUpperCase() as ExportFormat
+    if (!['PNG', 'JPG', 'WEBP'].includes(format)) {
+      printError(`Invalid format "${args.format}". Use png, jpg, or webp.`)
+      process.exit(1)
+    }
+
+    const graph = await loadDocument(args.file)
+    await loadFonts(graph)
+
+    const pages = graph.getPages()
+    const page = args.page
+      ? pages.find((p) => p.name === args.page)
+      : pages[0]
+
+    if (!page) {
+      printError(`Page "${args.page}" not found.`)
+      process.exit(1)
+    }
+
+    const ext = format.toLowerCase() === 'jpg' ? 'jpg' : format.toLowerCase()
+    const defaultName = basename(args.file, extname(args.file))
+    const output = resolve(args.output ?? `${defaultName}.${ext}`)
+
+    let data: Uint8Array | null
+
+    if (args.thumbnail) {
+      data = await exportThumbnail(graph, page.id, Number(args.width), Number(args.height))
+    } else {
+      const nodeIds = args.node ? [args.node] : page.childIds
+      data = await exportNodes(graph, page.id, nodeIds, {
+        scale: Number(args.scale),
+        format,
+        quality: args.quality ? Number(args.quality) : undefined
+      })
+    }
+
+    if (!data) {
+      printError('Nothing to export (empty page or no visible nodes).')
+      process.exit(1)
+    }
+
+    await Bun.write(output, data)
+    console.log(ok(`Exported ${output} (${(data.length / 1024).toFixed(1)} KB)`))
+  }
+})

package/src/commands/find.ts

@@ -0,0 +1,69 @@
+import { defineCommand } from 'citty'
+
+import { loadDocument } from '../headless'
+import { fmtList, nodeToListItem, printError, bold } from '../format'
+import type { SceneNode } from '@open-pencil/core'
+
+export default defineCommand({
+  meta: { description: 'Find nodes by name or type' },
+  args: {
+    file: { type: 'positional', description: '.fig file path', required: true },
+    name: { type: 'string', description: 'Node name (partial match, case-insensitive)' },
+    type: { type: 'string', description: 'Node type: FRAME, TEXT, RECTANGLE, INSTANCE, etc.' },
+    page: { type: 'string', description: 'Page name (default: all pages)' },
+    limit: { type: 'string', description: 'Max results (default: 100)', default: '100' },
+    json: { type: 'boolean', description: 'Output as JSON' }
+  },
+  async run({ args }) {
+    const graph = await loadDocument(args.file)
+    const pages = graph.getPages()
+    const max = Number(args.limit)
+    const namePattern = args.name?.toLowerCase()
+    const typeFilter = args.type?.toUpperCase()
+
+    const results: SceneNode[] = []
+
+    const searchPage = (pageNode: SceneNode) => {
+      const walk = (id: string) => {
+        if (results.length >= max) return
+        const node = graph.getNode(id)
+        if (!node) return
+        const matchesName = !namePattern || node.name.toLowerCase().includes(namePattern)
+        const matchesType = !typeFilter || node.type === typeFilter
+        if (matchesName && matchesType) results.push(node)
+        for (const childId of node.childIds) walk(childId)
+      }
+      for (const childId of pageNode.childIds) walk(childId)
+    }
+
+    if (args.page) {
+      const page = pages.find((p) => p.name === args.page)
+      if (!page) {
+        printError(`Page "${args.page}" not found.`)
+        process.exit(1)
+      }
+      searchPage(page)
+    } else {
+      for (const page of pages) searchPage(page)
+    }
+
+    if (args.json) {
+      console.log(JSON.stringify(results.map((n) => ({
+        id: n.id, name: n.name, type: n.type,
+        width: Math.round(n.width), height: Math.round(n.height)
+      })), null, 2))
+      return
+    }
+
+    if (results.length === 0) {
+      console.log('No nodes found.')
+      return
+    }
+
+    console.log('')
+    console.log(bold(`  Found ${results.length} node${results.length > 1 ? 's' : ''}`))
+    console.log('')
+    console.log(fmtList(results.map(nodeToListItem)))
+    console.log('')
+  }
+})

package/src/commands/info.ts

@@ -0,0 +1,58 @@
+import { defineCommand } from 'citty'
+
+import { loadDocument } from '../headless'
+import { bold, fmtHistogram, fmtSummary, kv } from '../format'
+import type { SceneNode } from '@open-pencil/core'
+
+export default defineCommand({
+  meta: { description: 'Show document info (pages, node counts, fonts)' },
+  args: {
+    file: { type: 'positional', description: '.fig file path', required: true },
+    json: { type: 'boolean', description: 'Output as JSON' }
+  },
+  async run({ args }) {
+    const graph = await loadDocument(args.file)
+    const pages = graph.getPages()
+
+    let totalNodes = 0
+    const types: Record<string, number> = {}
+    const fonts = new Set<string>()
+    const pageCounts: Record<string, number> = {}
+
+    for (const page of pages) {
+      let pageCount = 0
+      const walk = (id: string) => {
+        const node = graph.getNode(id) as SceneNode | undefined
+        if (!node) return
+        totalNodes++
+        pageCount++
+        types[node.type] = (types[node.type] ?? 0) + 1
+        if (node.fontFamily) fonts.add(node.fontFamily)
+        for (const childId of node.childIds) walk(childId)
+      }
+      for (const childId of page.childIds) walk(childId)
+      pageCounts[page.name] = pageCount
+    }
+
+    if (args.json) {
+      console.log(JSON.stringify({ pages: pages.length, totalNodes, types, fonts: [...fonts].sort(), pageCounts }, null, 2))
+      return
+    }
+
+    console.log('')
+    console.log(bold(`  ${pages.length} pages, ${totalNodes} nodes`))
+    console.log('')
+
+    const pageItems = Object.entries(pageCounts).map(([label, value]) => ({ label, value }))
+    console.log(fmtHistogram(pageItems, { unit: 'nodes' }))
+
+    console.log('')
+    console.log(fmtSummary(types))
+
+    if (fonts.size > 0) {
+      console.log('')
+      console.log(kv('Fonts', [...fonts].sort().join(', ')))
+    }
+    console.log('')
+  }
+})

package/src/commands/node.ts

@@ -0,0 +1,83 @@
+import { defineCommand } from 'citty'
+
+import { loadDocument } from '../headless'
+import { fmtNode, fmtList, nodeToData, nodeDetails, formatType, printError } from '../format'
+import type { SceneNode, SceneGraph } from '@open-pencil/core'
+
+function fullNodeDetails(graph: SceneGraph, node: SceneNode): Record<string, unknown> {
+  const details = nodeDetails(node)
+
+  const parent = node.parentId ? graph.getNode(node.parentId) : undefined
+  if (parent) details.parent = `${parent.name} (${parent.id})`
+
+  if (node.text) {
+    details.text = node.text.length > 80 ? node.text.slice(0, 80) + '…' : node.text
+  }
+
+  if (node.childIds.length > 0) details.children = node.childIds.length
+
+  for (const [field, varId] of Object.entries(node.boundVariables)) {
+    const variable = graph.variables.get(varId)
+    details[`var:${field}`] = variable?.name ?? varId
+  }
+
+  return details
+}
+
+export default defineCommand({
+  meta: { description: 'Show detailed node properties by ID' },
+  args: {
+    file: { type: 'positional', description: '.fig file path', required: true },
+    id: { type: 'string', description: 'Node ID', required: true },
+    json: { type: 'boolean', description: 'Output as JSON' }
+  },
+  async run({ args }) {
+    const graph = await loadDocument(args.file)
+    const node = graph.getNode(args.id)
+
+    if (!node) {
+      printError(`Node "${args.id}" not found.`)
+      process.exit(1)
+    }
+
+    if (args.json) {
+      const { childIds, parentId, ...rest } = node
+      const children = childIds.length
+      const parent = parentId ? graph.getNode(parentId) : undefined
+      console.log(
+        JSON.stringify(
+          {
+            ...rest,
+            parent: parent ? { id: parent.id, name: parent.name, type: parent.type } : null,
+            children
+          },
+          null,
+          2
+        )
+      )
+      return
+    }
+
+    console.log('')
+    console.log(fmtNode(nodeToData(node), fullNodeDetails(graph, node)))
+
+    if (node.childIds.length > 0) {
+      const children = node.childIds
+        .map((id) => graph.getNode(id))
+        .filter((n): n is SceneNode => n !== undefined)
+        .slice(0, 10)
+        .map((child) => ({
+          header: `[${formatType(child.type)}] "${child.name}" (${child.id})`
+        }))
+
+      if (node.childIds.length > 10) {
+        children.push({ header: `… and ${node.childIds.length - 10} more` })
+      }
+
+      console.log('')
+      console.log(fmtList(children, { compact: true }))
+    }
+
+    console.log('')
+  }
+})

package/src/commands/pages.ts

@@ -0,0 +1,53 @@
+import { defineCommand } from 'citty'
+
+import { loadDocument } from '../headless'
+import { bold, fmtList, entity, formatType } from '../format'
+
+export default defineCommand({
+  meta: { description: 'List pages in a .fig file' },
+  args: {
+    file: { type: 'positional', description: '.fig file path', required: true },
+    json: { type: 'boolean', description: 'Output as JSON' }
+  },
+  async run({ args }) {
+    const graph = await loadDocument(args.file)
+    const pages = graph.getPages()
+
+    const countNodes = (pageId: string): number => {
+      let count = 0
+      const walk = (id: string) => {
+        count++
+        const n = graph.getNode(id)
+        if (n) for (const cid of n.childIds) walk(cid)
+      }
+      const page = graph.getNode(pageId)
+      if (page) for (const cid of page.childIds) walk(cid)
+      return count
+    }
+
+    if (args.json) {
+      console.log(
+        JSON.stringify(
+          pages.map((p) => ({ id: p.id, name: p.name, nodes: countNodes(p.id) })),
+          null,
+          2
+        )
+      )
+      return
+    }
+
+    console.log('')
+    console.log(bold(`  ${pages.length} page${pages.length !== 1 ? 's' : ''}`))
+    console.log('')
+    console.log(
+      fmtList(
+        pages.map((page) => ({
+          header: entity(formatType(page.type), page.name, page.id),
+          details: { nodes: countNodes(page.id) }
+        })),
+        { compact: true }
+      )
+    )
+    console.log('')
+  }
+})

package/src/commands/tree.ts

@@ -0,0 +1,63 @@
+import { defineCommand } from 'citty'
+
+import { loadDocument } from '../headless'
+import { fmtTree, nodeToTreeNode, printError, entity, formatType } from '../format'
+import type { SceneNode } from '@open-pencil/core'
+
+export default defineCommand({
+  meta: { description: 'Print the node tree' },
+  args: {
+    file: { type: 'positional', description: '.fig file path', required: true },
+    page: { type: 'string', description: 'Page name (default: first page)' },
+    depth: { type: 'string', description: 'Max depth (default: unlimited)' },
+    json: { type: 'boolean', description: 'Output as JSON' }
+  },
+  async run({ args }) {
+    const graph = await loadDocument(args.file)
+    const pages = graph.getPages()
+    const maxDepth = args.depth ? Number(args.depth) : Infinity
+
+    const page = args.page
+      ? pages.find((p) => p.name === args.page)
+      : pages[0]
+
+    if (!page) {
+      printError(`Page "${args.page}" not found. Available: ${pages.map((p) => p.name).join(', ')}`)
+      process.exit(1)
+    }
+
+    if (args.json) {
+      const buildJson = (id: string, depth: number): unknown => {
+        const node = graph.getNode(id)
+        if (!node) return null
+        const result: Record<string, unknown> = {
+          id: node.id,
+          name: node.name,
+          type: node.type,
+          x: Math.round(node.x),
+          y: Math.round(node.y),
+          width: Math.round(node.width),
+          height: Math.round(node.height)
+        }
+        if (node.childIds.length > 0 && depth < maxDepth) {
+          result.children = node.childIds.map((cid) => buildJson(cid, depth + 1)).filter(Boolean)
+        }
+        return result
+      }
+      console.log(JSON.stringify(page.childIds.map((id) => buildJson(id, 0)), null, 2))
+      return
+    }
+
+    const root = {
+      header: entity(formatType(page.type), page.name, page.id),
+      children: page.childIds
+        .map((id) => graph.getNode(id))
+        .filter((n): n is SceneNode => n !== undefined)
+        .map((child) => nodeToTreeNode(graph, child, maxDepth))
+    }
+
+    console.log('')
+    console.log(fmtTree(root, { maxDepth }))
+    console.log('')
+  }
+})

package/src/commands/variables.ts

@@ -0,0 +1,95 @@
+import { defineCommand } from 'citty'
+
+import { loadDocument } from '../headless'
+import { bold, fmtList, fmtSummary } from '../format'
+import type { SceneGraph, Variable } from '@open-pencil/core'
+
+function formatValue(variable: Variable, graph: SceneGraph): string {
+  const modeId = graph.getActiveModeId(variable.collectionId)
+  const raw = variable.valuesByMode[modeId]
+  if (raw === undefined) return '–'
+
+  if (typeof raw === 'object' && raw !== null && 'aliasId' in raw) {
+    const alias = graph.variables.get(raw.aliasId)
+    return alias ? `→ ${alias.name}` : `→ ${raw.aliasId}`
+  }
+
+  if (typeof raw === 'object' && 'r' in raw) {
+    const { r, g, b } = raw as { r: number; g: number; b: number }
+    return (
+      '#' +
+      [r, g, b]
+        .map((c) =>
+          Math.round(c * 255)
+            .toString(16)
+            .padStart(2, '0')
+        )
+        .join('')
+    )
+  }
+
+  return String(raw)
+}
+
+export default defineCommand({
+  meta: { description: 'List design variables and collections' },
+  args: {
+    file: { type: 'positional', description: '.fig file path', required: true },
+    collection: { type: 'string', description: 'Filter by collection name' },
+    type: { type: 'string', description: 'Filter by type: COLOR, FLOAT, STRING, BOOLEAN' },
+    json: { type: 'boolean', description: 'Output as JSON' }
+  },
+  async run({ args }) {
+    const graph = await loadDocument(args.file)
+
+    const collections = [...graph.variableCollections.values()]
+    const variables = [...graph.variables.values()]
+
+    if (variables.length === 0) {
+      console.log('No variables found.')
+      return
+    }
+
+    if (args.json) {
+      console.log(JSON.stringify({ collections, variables }, null, 2))
+      return
+    }
+
+    const typeFilter = args.type?.toUpperCase()
+    const collFilter = args.collection?.toLowerCase()
+
+    console.log('')
+
+    for (const coll of collections) {
+      if (collFilter && !coll.name.toLowerCase().includes(collFilter)) continue
+
+      const collVars = graph
+        .getVariablesForCollection(coll.id)
+        .filter((v) => !typeFilter || v.type === typeFilter)
+
+      if (collVars.length === 0) continue
+
+      const modes = coll.modes.map((m) => m.name).join(', ')
+      console.log(bold(`  ${coll.name}`) + ` (${modes})`)
+      console.log('')
+      console.log(
+        fmtList(
+          collVars.map((v) => ({
+            header: v.name,
+            details: { value: formatValue(v, graph), type: v.type.toLowerCase() }
+          })),
+          { compact: true }
+        )
+      )
+      console.log('')
+    }
+
+    console.log(
+      fmtSummary({
+        variables: variables.length,
+        collections: collections.length
+      })
+    )
+    console.log('')
+  }
+})