@open-pencil/cli 0.10.0 → 0.11.0

package/src/commands/find.ts

@@ -1,14 +1,23 @@
 import { defineCommand } from 'citty'
 
-import { loadDocument } from '../headless'
-import { isAppMode, requireFile, rpc } from '../app-client'
-import { fmtList, bold, entity, formatType } from '../format'
 import { executeRpcCommand } from '@open-pencil/core'
 
+import { isAppMode, requireFile, rpc } from '../app-client'
+import { printNodeResults } from '../format'
+import { loadDocument } from '../headless'
+
 import type { FindNodeResult } from '@open-pencil/core'
 
-async function getData(file: string | undefined, args: { name?: string; type?: string; page?: string; limit?: string }): Promise<FindNodeResult[]> {
-  const rpcArgs = { name: args.name, type: args.type, page: args.page, limit: args.limit ? Number(args.limit) : undefined }
+async function getData(
+  file: string | undefined,
+  args: { name?: string; type?: string; page?: string; limit?: string }
+): Promise<FindNodeResult[]> {
+  const rpcArgs = {
+    name: args.name,
+    type: args.type,
+    page: args.page,
+    limit: args.limit ? Number(args.limit) : undefined
+  }
   if (isAppMode(file)) return rpc<FindNodeResult[]>('find', rpcArgs)
   const graph = await loadDocument(requireFile(file))
   return executeRpcCommand(graph, 'find', rpcArgs) as FindNodeResult[]
@@ -17,7 +26,11 @@ async function getData(file: string | undefined, args: { name?: string; type?: s
 export default defineCommand({
   meta: { description: 'Find nodes by name or type' },
   args: {
-    file: { type: 'positional', description: '.fig file path (omit to connect to running app)', required: false },
+    file: {
+      type: 'positional',
+      description: 'Document file path (omit to connect to running app)',
+      required: false
+    },
     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)' },
@@ -32,21 +45,6 @@ export default defineCommand({
       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((n) => ({
-          header: entity(formatType(n.type), n.name, n.id)
-        }))
-      )
-    )
-    console.log('')
+    printNodeResults(results)
   }
 })

package/src/commands/formats.ts

@@ -0,0 +1,80 @@
+import { defineCommand } from 'citty'
+
+import { BUILTIN_IO_FORMATS, IORegistry } from '@open-pencil/core'
+
+import { bold, fmtList, kv } from '../format'
+
+const io = new IORegistry(BUILTIN_IO_FORMATS)
+
+function supportLabels(format: ReturnType<IORegistry['listFormats']>[number]): string[] {
+  const labels: string[] = []
+  if (format.support.readDocument) labels.push('read')
+  if (format.support.writeDocument) labels.push('write')
+  if (format.support.exportDocument) labels.push('export-document')
+  if (format.support.exportPage) labels.push('export-page')
+  if (format.support.exportSelection) labels.push('export-selection')
+  if (format.support.exportNode) labels.push('export-node')
+  return labels
+}
+
+export default defineCommand({
+  meta: { description: 'List supported document and export formats' },
+  args: {
+    json: { type: 'boolean', description: 'Output as JSON' }
+  },
+  async run({ args }) {
+    const formats = io.listFormats().map((format) => ({
+      id: format.id,
+      label: format.label,
+      role: format.role,
+      category: format.category,
+      extensions: format.extensions,
+      mimeTypes: format.mimeTypes,
+      support: supportLabels(format)
+    }))
+
+    if (args.json) {
+      console.log(JSON.stringify(formats, null, 2))
+      return
+    }
+
+    console.log('')
+    console.log(bold(`  ${formats.length} format${formats.length !== 1 ? 's' : ''}`))
+    console.log('')
+    console.log(
+      fmtList(
+        formats.map((format) => ({
+          header: `${format.label} (${format.id})`,
+          details: {
+            role: format.role,
+            category: format.category,
+            ext: format.extensions.map((ext) => `.${ext}`).join(', '),
+            support: format.support.join(', '),
+            mime: format.mimeTypes.join(', ')
+          }
+        })),
+        { compact: true }
+      )
+    )
+    console.log('')
+    console.log(
+      kv(
+        'Readable',
+        io
+          .listReadableFormats()
+          .map((f) => f.id)
+          .join(', ') || 'none'
+      )
+    )
+    console.log(
+      kv(
+        'Writable',
+        io
+          .listWritableFormats()
+          .map((f) => f.id)
+          .join(', ') || 'none'
+      )
+    )
+    console.log('')
+  }
+})

package/src/commands/info.ts

@@ -1,11 +1,12 @@
 import { defineCommand } from 'citty'
 
-import { loadDocument } from '../headless'
+import { executeRpcCommand } from '@open-pencil/core'
+
 import { isAppMode, requireFile, rpc } from '../app-client'
 import { bold, fmtHistogram, fmtSummary, kv } from '../format'
+import { loadDocument } from '../headless'
 
 import type { InfoResult } from '@open-pencil/core'
-import { executeRpcCommand } from '@open-pencil/core'
 
 async function getData(file?: string): Promise<InfoResult> {
   if (isAppMode(file)) return rpc<InfoResult>('info')
@@ -16,7 +17,11 @@ async function getData(file?: string): Promise<InfoResult> {
 export default defineCommand({
   meta: { description: 'Show document info (pages, node counts, fonts)' },
   args: {
-    file: { type: 'positional', description: '.fig file path (omit to connect to running app)', required: false },
+    file: {
+      type: 'positional',
+      description: 'Document file path (omit to connect to running app)',
+      required: false
+    },
     json: { type: 'boolean', description: 'Output as JSON' }
   },
   async run({ args }) {

package/src/commands/lint.ts

@@ -0,0 +1,86 @@
+import { defineCommand } from 'citty'
+
+import { allRules, createLinter, presets, type LintMessage } from '@open-pencil/core'
+
+import { bold, dim, fail, fmtList, ok } from '../format'
+import { loadDocument } from '../headless'
+
+function formatSeverity(severity: LintMessage['severity']) {
+  if (severity === 'error') return fail('error')
+  if (severity === 'warning') return fail('warn')
+  return ok('info')
+}
+
+function formatMessage(message: LintMessage) {
+  return {
+    header: `${formatSeverity(message.severity)} ${bold(message.ruleId)} ${dim(message.nodePath.join(' / '))}`,
+    details: {
+      message: message.message,
+      node: `${message.nodeName} (${message.nodeId})`,
+      suggest: message.suggest
+    }
+  }
+}
+
+export default defineCommand({
+  meta: {
+    name: 'lint',
+    description: 'Lint design documents for consistency, structure, and accessibility issues'
+  },
+  args: {
+    file: {
+      type: 'positional',
+      required: true,
+      description: 'Design document to lint (.fig, .pen)'
+    },
+    preset: {
+      type: 'string',
+      default: 'recommended',
+      description: 'Preset: recommended, strict, accessibility'
+    },
+    rule: { type: 'string', description: 'Run specific rule(s) only (repeatable)' },
+    json: { type: 'boolean', default: false, description: 'Output as JSON' },
+    'list-rules': { type: 'boolean', default: false, description: 'List rules and exit' }
+  },
+  async run({ args }) {
+    if (args['list-rules']) {
+      console.log('')
+      console.log(bold('Available rules'))
+      console.log('')
+      console.log(
+        fmtList(
+          Object.entries(allRules).map(([id, rule]) => ({
+            header: bold(id),
+            details: { category: rule.meta.category, description: rule.meta.description }
+          }))
+        )
+      )
+      console.log('')
+      console.log(bold(`Presets: ${Object.keys(presets).join(', ')}`))
+      console.log('')
+      return
+    }
+
+    const graph = await loadDocument(args.file)
+    const rules = args.rule ? (Array.isArray(args.rule) ? args.rule : [args.rule]) : undefined
+    const result = createLinter({ preset: args.preset, rules }).lintGraph(graph)
+
+    if (args.json) {
+      console.log(JSON.stringify(result, null, 2))
+    } else if (result.messages.length === 0) {
+      console.log(ok('No lint issues found.'))
+    } else {
+      console.log('')
+      console.log(
+        bold(
+          `Lint issues: ${result.errorCount} errors, ${result.warningCount} warnings, ${result.infoCount} info`
+        )
+      )
+      console.log('')
+      console.log(fmtList(result.messages.map(formatMessage)))
+      console.log('')
+    }
+
+    if (result.errorCount > 0) process.exit(1)
+  }
+})

package/src/commands/node.ts

@@ -1,13 +1,17 @@
 import { defineCommand } from 'citty'
 
-import { loadDocument } from '../headless'
+import { executeRpcCommand, colorToHex } from '@open-pencil/core'
+
 import { isAppMode, requireFile, rpc } from '../app-client'
 import { fmtNode, printError, formatType } from '../format'
-import { executeRpcCommand, colorToHex } from '@open-pencil/core'
+import { loadDocument } from '../headless'
 
 import type { Color, NodeResult } from '@open-pencil/core'
 
-async function getData(file: string | undefined, id: string): Promise<NodeResult | { error: string }> {
+async function getData(
+  file: string | undefined,
+  id: string
+): Promise<NodeResult | { error: string }> {
   if (isAppMode(file)) return rpc<NodeResult>('node', { id })
   const graph = await loadDocument(requireFile(file))
   return executeRpcCommand(graph, 'node', { id }) as NodeResult | { error: string }
@@ -16,7 +20,11 @@ async function getData(file: string | undefined, id: string): Promise<NodeResult
 export default defineCommand({
   meta: { description: 'Show detailed node properties by ID' },
   args: {
-    file: { type: 'positional', description: '.fig file path (omit to connect to running app)', required: false },
+    file: {
+      type: 'positional',
+      description: 'Document file path (omit to connect to running app)',
+      required: false
+    },
     id: { type: 'string', description: 'Node ID', required: true },
     json: { type: 'boolean', description: 'Output as JSON' }
   },
@@ -47,8 +55,9 @@ export default defineCommand({
     if (data.parent) details.parent = `${data.parent.name} (${data.parent.id})`
     if (data.text) details.text = data.text
     if (data.fills.length > 0) {
-      const solid = (data.fills as Array<{ type: string; visible: boolean; color: Color; opacity: number }>)
-        .find((f) => f.type === 'SOLID' && f.visible)
+      const solid = (
+        data.fills as Array<{ type: string; visible: boolean; color: Color; opacity: number }>
+      ).find((f) => f.type === 'SOLID' && f.visible)
       if (solid) {
         const hex = colorToHex(solid.color)
         details.fill = solid.opacity < 1 ? `${hex} ${Math.round(solid.opacity * 100)}%` : hex

package/src/commands/pages.ts

@@ -1,11 +1,12 @@
 import { defineCommand } from 'citty'
 
-import { loadDocument } from '../headless'
+import { executeRpcCommand } from '@open-pencil/core'
+
 import { isAppMode, requireFile, rpc } from '../app-client'
 import { bold, fmtList, entity } from '../format'
+import { loadDocument } from '../headless'
 
 import type { PageItem } from '@open-pencil/core'
-import { executeRpcCommand } from '@open-pencil/core'
 
 async function getData(file?: string): Promise<PageItem[]> {
   if (isAppMode(file)) return rpc<PageItem[]>('pages')
@@ -14,9 +15,13 @@ async function getData(file?: string): Promise<PageItem[]> {
 }
 
 export default defineCommand({
-  meta: { description: 'List pages in a .fig file' },
+  meta: { description: 'List pages in a document' },
   args: {
-    file: { type: 'positional', description: '.fig file path (omit to connect to running app)', required: false },
+    file: {
+      type: 'positional',
+      description: 'Document file path (omit to connect to running app)',
+      required: false
+    },
     json: { type: 'boolean', description: 'Output as JSON' }
   },
   async run({ args }) {

package/src/commands/query.ts

@@ -1,10 +1,11 @@
 import { defineCommand } from 'citty'
 
-import { loadDocument } from '../headless'
-import { isAppMode, requireFile, rpc } from '../app-client'
-import { fmtList, printError, bold, entity, formatType } from '../format'
 import { executeRpcCommand } from '@open-pencil/core'
 
+import { isAppMode, requireFile, rpc } from '../app-client'
+import { printNodeResults, printError } from '../format'
+import { loadDocument } from '../headless'
+
 import type { QueryNodeResult } from '@open-pencil/core'
 
 async function getData(
@@ -18,7 +19,7 @@ async function getData(
   }
   if (isAppMode(file)) return rpc<QueryNodeResult[]>('query', rpcArgs)
   const graph = await loadDocument(requireFile(file))
-  return await executeRpcCommand(graph, 'query', rpcArgs) as QueryNodeResult[] | { error: string }
+  return (await executeRpcCommand(graph, 'query', rpcArgs)) as QueryNodeResult[] | { error: string }
 }
 
 export default defineCommand({
@@ -30,19 +31,18 @@ Examples:
   open-pencil query file.fig "//FRAME[@width < 300]"                # Frames narrower than 300px
   open-pencil query file.fig "//COMPONENT[starts-with(@name, 'Button')]"  # Components starting with Button
   open-pencil query file.fig "//SECTION/FRAME"                      # Direct frame children of sections
-  open-pencil query file.fig "//SECTION//TEXT"                       # All text inside sections
+  open-pencil query file.fig "//SECTION//TEXT"                      # All text inside sections
   open-pencil query file.fig "//*[@cornerRadius > 0]"               # Any node with corner radius`
   },
   args: {
     file: {
       type: 'positional',
-      description: '.fig file path (omit to connect to running app)',
+      description: 'Document file path (omit to connect to running app)',
       required: false
     },
     selector: {
       type: 'positional',
-      description:
-        'XPath selector (e.g., //FRAME[@width < 300], //TEXT[contains(@name, "Label")])',
+      description: 'XPath selector (e.g., //FRAME[@width < 300], //TEXT[contains(@name, "Label")])',
       required: true
     },
     page: { type: 'string', description: 'Page name (default: all pages)' },
@@ -66,25 +66,9 @@ Examples:
       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((n) => ({
-          header: entity(
-            formatType(n.type),
-            `${n.name}  ${n.width}×${n.height}`,
-            n.id
-          )
-        }))
-      )
-    )
-    console.log('')
+    printNodeResults(results, (n) => {
+      const q = n as { width?: number; height?: number; name: string }
+      return `${q.name}  ${q.width}×${q.height}`
+    })
   }
 })

package/src/commands/tree.ts

@@ -1,9 +1,10 @@
 import { defineCommand } from 'citty'
 
-import { loadDocument } from '../headless'
+import { executeRpcCommand } from '@open-pencil/core'
+
 import { isAppMode, requireFile, rpc } from '../app-client'
 import { fmtTree, printError, entity, formatType } from '../format'
-import { executeRpcCommand } from '@open-pencil/core'
+import { loadDocument } from '../headless'
 
 import type { TreeResult, TreeNodeResult } from '@open-pencil/core'
 import type { TreeNode } from 'agentfmt'
@@ -18,7 +19,10 @@ function toAgentfmtTree(node: TreeNodeResult, maxDepth: number, depth = 0): Tree
   return treeNode
 }
 
-async function getData(file: string | undefined, args: { page?: string; depth?: string }): Promise<TreeResult | { error: string }> {
+async function getData(
+  file: string | undefined,
+  args: { page?: string; depth?: string }
+): Promise<TreeResult | { error: string }> {
   const rpcArgs = { page: args.page, depth: args.depth ? Number(args.depth) : undefined }
   if (isAppMode(file)) return rpc<TreeResult>('tree', rpcArgs)
   const graph = await loadDocument(requireFile(file))
@@ -28,7 +32,11 @@ async function getData(file: string | undefined, args: { page?: string; depth?:
 export default defineCommand({
   meta: { description: 'Print the node tree' },
   args: {
-    file: { type: 'positional', description: '.fig file path (omit to connect to running app)', required: false },
+    file: {
+      type: 'positional',
+      description: 'Document file path (omit to connect to running app)',
+      required: false
+    },
     page: { type: 'string', description: 'Page name (default: first page)' },
     depth: { type: 'string', description: 'Max depth (default: unlimited)' },
     json: { type: 'boolean', description: 'Output as JSON' }

package/src/commands/variables.ts

@@ -1,13 +1,17 @@
 import { defineCommand } from 'citty'
 
-import { loadDocument } from '../headless'
+import { executeRpcCommand } from '@open-pencil/core'
+
 import { isAppMode, requireFile, rpc } from '../app-client'
 import { bold, entity, fmtList, fmtSummary } from '../format'
-import { executeRpcCommand } from '@open-pencil/core'
+import { loadDocument } from '../headless'
 
 import type { VariablesResult } from '@open-pencil/core'
 
-async function getData(file: string | undefined, args: { collection?: string; type?: string }): Promise<VariablesResult> {
+async function getData(
+  file: string | undefined,
+  args: { collection?: string; type?: string }
+): Promise<VariablesResult> {
   const rpcArgs = { collection: args.collection, type: args.type }
   if (isAppMode(file)) return rpc<VariablesResult>('variables', rpcArgs)
   const graph = await loadDocument(requireFile(file))
@@ -17,7 +21,11 @@ async function getData(file: string | undefined, args: { collection?: string; ty
 export default defineCommand({
   meta: { description: 'List design variables and collections' },
   args: {
-    file: { type: 'positional', description: '.fig file path (omit to connect to running app)', required: false },
+    file: {
+      type: 'positional',
+      description: 'Document file path (omit to connect to running app)',
+      required: false
+    },
     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' }

package/src/format.ts

@@ -13,10 +13,45 @@ import {
   histogram as fmtHistogram,
   summary as fmtSummary
 } from 'agentfmt'
-import type { TreeNode, ListItem, NodeData } from 'agentfmt'
+
 import type { SceneNode, SceneGraph } from '@open-pencil/core'
+import type { TreeNode, ListItem, NodeData } from 'agentfmt'
+
+export {
+  ok,
+  fail,
+  dim,
+  bold,
+  cyan,
+  entity,
+  kv,
+  fmtTree,
+  fmtList,
+  fmtNode,
+  fmtHistogram,
+  fmtSummary
+}
 
-export { ok, fail, dim, bold, cyan, entity, kv, fmtTree, fmtList, fmtNode, fmtHistogram, fmtSummary }
+export function printNodeResults(
+  results: Array<{ type: string; name: string; id: string }>,
+  formatLabel: (n: { type: string; name: string; id: string }) => string = (n) => n.name
+): void {
+  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((n) => ({
+        header: entity(formatType(n.type), formatLabel(n), n.id)
+      }))
+    )
+  )
+  console.log('')
+}
 
 const TYPE_LABELS: Record<string, string> = {
   FRAME: 'frame',
@@ -42,7 +77,12 @@ export function formatType(type: string): string {
 }
 
 export function formatBox(node: SceneNode): string {
-  return fmtBox(Math.round(node.width), Math.round(node.height), Math.round(node.x), Math.round(node.y))
+  return fmtBox(
+    Math.round(node.width),
+    Math.round(node.height),
+    Math.round(node.x),
+    Math.round(node.y)
+  )
 }
 
 function formatFill(node: SceneNode): string | null {
@@ -50,7 +90,15 @@ function formatFill(node: SceneNode): string | null {
   const solid = node.fills.find((f) => f.type === 'SOLID' && f.visible)
   if (!solid?.color) return null
   const { r, g, b } = solid.color
-  const hex = '#' + [r, g, b].map((c) => Math.round(c * 255).toString(16).padStart(2, '0')).join('')
+  const hex =
+    '#' +
+    [r, g, b]
+      .map((c) =>
+        Math.round(c * 255)
+          .toString(16)
+          .padStart(2, '0')
+      )
+      .join('')
   return solid.opacity < 1 ? `${hex} ${Math.round(solid.opacity * 100)}%` : hex
 }
 
@@ -58,7 +106,15 @@ function formatStroke(node: SceneNode): string | null {
   if (!node.strokes.length) return null
   const s = node.strokes[0]
   const { r, g, b } = s.color
-  const hex = '#' + [r, g, b].map((c) => Math.round(c * 255).toString(16).padStart(2, '0')).join('')
+  const hex =
+    '#' +
+    [r, g, b]
+      .map((c) =>
+        Math.round(c * 255)
+          .toString(16)
+          .padStart(2, '0')
+      )
+      .join('')
   return `${hex} ${s.weight}px`
 }
 
@@ -122,7 +178,12 @@ export function nodeDetails(node: SceneNode): Record<string, unknown> {
   return details
 }
 
-export function nodeToTreeNode(graph: SceneGraph, node: SceneNode, maxDepth: number, depth = 0): TreeNode {
+export function nodeToTreeNode(
+  graph: SceneGraph,
+  node: SceneNode,
+  maxDepth: number,
+  depth = 0
+): TreeNode {
   const treeNode: TreeNode = {
     header: entity(formatType(node.type), node.name, node.id),
     details: nodeDetails(node)

package/src/headless.ts

@@ -1,36 +1,18 @@
 import {
-  parseFigFile,
-  initCanvasKit,
-  type SceneGraph,
-  type ExportFormat,
+  BUILTIN_IO_FORMATS,
+  IORegistry,
   computeAllLayouts,
-  headlessRenderNodes,
-  headlessRenderThumbnail
+  initCanvasKit,
+  type SceneGraph
 } from '@open-pencil/core'
 
 export { initCanvasKit }
 
+const io = new IORegistry(BUILTIN_IO_FORMATS)
+
 export async function loadDocument(filePath: string): Promise<SceneGraph> {
-  const data = await Bun.file(filePath).arrayBuffer()
-  const graph = await parseFigFile(data)
+  const bytes = new Uint8Array(await Bun.file(filePath).arrayBuffer())
+  const { graph } = await io.readDocument({ name: filePath, data: bytes })
   computeAllLayouts(graph)
   return graph
 }
-
-export async function exportNodes(
-  graph: SceneGraph,
-  pageId: string,
-  nodeIds: string[],
-  options: { scale?: number; format?: ExportFormat; quality?: number }
-): Promise<Uint8Array | null> {
-  return headlessRenderNodes(graph, pageId, nodeIds, options)
-}
-
-export async function exportThumbnail(
-  graph: SceneGraph,
-  pageId: string,
-  width: number,
-  height: number
-): Promise<Uint8Array | null> {
-  return headlessRenderThumbnail(graph, pageId, width, height)
-}

package/src/index.ts

@@ -2,13 +2,16 @@
 import { defineCommand, runMain } from 'citty'
 
 import analyze from './commands/analyze'
+import convert from './commands/convert'
 import evalCmd from './commands/eval'
 import exportCmd from './commands/export'
 import find from './commands/find'
+import formats from './commands/formats'
 import info from './commands/info'
-import query from './commands/query'
+import lint from './commands/lint'
 import node from './commands/node'
 import pages from './commands/pages'
+import query from './commands/query'
 import tree from './commands/tree'
 import variables from './commands/variables'
 
@@ -17,15 +20,18 @@ const { version } = await import('../package.json')
 const main = defineCommand({
   meta: {
     name: 'open-pencil',
-    description: 'OpenPencil CLI — inspect, export, and lint .fig design files',
+    description: 'OpenPencil CLI — inspect, export, and lint OpenPencil design documents',
     version
   },
   subCommands: {
     analyze,
+    convert,
     eval: evalCmd,
     export: exportCmd,
     find,
+    formats,
     info,
+    lint,
     query,
     node,
     pages,