AI-native design editor. Open-source Figma alternative.
import { mkdir, writeFile } from 'node:fs/promises'
import { basename, dirname, extname, join, resolve } from 'node:path'
import { defineCommand } from 'citty'
import { toUint8Array } from 'js-base64'
import { BUILTIN_IO_FORMATS, IORegistry, type ExportResult } from '@open-pencil/core/io'
import type { AutomationDocumentSummary } from '@open-pencil/core/rpc'
import { isAppMode, requireFile, rpc } from '#cli/app/client'
import { appTargetOptions, appTargetRPCArgs } from '#cli/app/target'
import { ok, printError } from '#cli/format'
import {
loadDocument,
populateDocumentPage,
populateWholeDocument,
requirePage
} from '#cli/headless'
import { applyExportFontPolicy, exportFontRoots, FONT_POLICIES } from './font-policy'
import { exportStorybookFromFile } from './storybook'
const io = new IORegistry(BUILTIN_IO_FORMATS)
// Storybook writes a folder of stories, so it stays a CLI command beside the IO formats.
const FORMAT_IDS = [...io.listExportFormats('node').map((format) => format.id), 'storybook']
const ALL_FORMATS = new Set(FORMAT_IDS.map((id) => id.toUpperCase()))
const FORMAT_LIST = `${FORMAT_IDS.slice(0, -1).join(', ')}, or ${FORMAT_IDS.at(-1)}`
function formatSupportsScale(format: string): boolean {
return io.getFormat(format.toLowerCase())?.exportOptions?.scale ?? false
}
const JSX_STYLES = new Set(['openpencil', 'tailwind'])
const HTML_STYLES = new Set(['inline', 'tailwind'])
const HTML_MODES = new Set(['fragment', 'standalone'])
const HTML_ASSETS = new Set(['inline', 'external'])
const HTML_FONTS = new Set(['assets', 'none'])
export interface ExportArgs {
file?: string
output?: string
format: string
scale: string
quality?: string
page?: string
node?: string
style: string
html: string
css: string
assets: string
fonts?: string
framework: string
'design-images': boolean
watch?: boolean
'font-policy': string
thumbnail?: boolean
width: string
height: string
'document-id'?: string
'page-id'?: string
}
async function writeAndLog(path: string, content: string | Uint8Array) {
await writeFile(path, content)
const size = typeof content === 'string' ? content.length : content.length
console.log(ok(`Exported ${path} (${(size / 1024).toFixed(1)} KB)`))
}
/** The app addresses pages by ID, so look the `--page` name up in the target document. */
async function appPageId(args: ExportArgs, pageName: string): Promise<string> {
const { documents } = await rpc<{ documents: AutomationDocumentSummary[] }>('list_documents')
const documentId = args['document-id']
const document = documents.find((doc) => (documentId ? doc.id === documentId : doc.active))
if (!document) {
printError(documentId ? `Document "${documentId}" not found.` : 'No active document.')
process.exit(1)
}
const page = document.pages.find((candidate) => candidate.name === pageName)
if (!page) {
const available = document.pages.map((candidate) => candidate.name).join(', ')
printError(`Page "${pageName}" not found. Available: ${available}`)
process.exit(1)
}
return page.id
}
async function appExportTarget(args: ExportArgs) {
const target = appTargetRPCArgs(args)
if (!args.page) return target
if (args.node || args['page-id']) {
printError(`--page and ${args.node ? '--node' : '--page-id'} cannot be used together.`)
process.exit(1)
}
target.page_id = await appPageId(args, args.page)
return target
}
async function exportViaApp(format: string, args: ExportArgs) {
const targetArgs = await appExportTarget(args)
if (format === 'SVG') {
const result = await rpc<{ svg: string }>('tool', {
...targetArgs,
name: 'export_svg',
args: { ids: args.node ? [args.node] : undefined }
})
if (!result.svg) {
printError('Nothing to export.')
process.exit(1)
}
await writeAndLog(resolve(args.output ?? 'export.svg'), result.svg)
return
}
if (format === 'PDF') {
const result = await rpc<{ base64: string }>('tool', {
...targetArgs,
name: 'export_pdf',
args: { ids: args.node ? [args.node] : undefined }
})
if (!result.base64) {
printError('Nothing to export.')
process.exit(1)
}
const data = toUint8Array(result.base64)
await writeAndLog(resolve(args.output ?? 'export.pdf'), data)
return
}
if (
format === 'JSX' ||
format === 'HTML' ||
format === 'FIG' ||
format === 'PPTX' ||
format === 'STORYBOOK'
) {
printError(`${format} export is only available in file mode right now.`)
process.exit(1)
}
const result = await rpc<{ base64: string }>('export', {
...targetArgs,
nodeIds: args.node ? [args.node] : undefined,
// Without a node or a page the app exports the selection.
scope: !args.node && targetArgs.page_id ? 'page' : undefined,
scale: Number(args.scale),
format: format.toLowerCase()
})
const data = toUint8Array(result.base64)
const ext = format.toLowerCase() === 'jpg' ? 'jpg' : format.toLowerCase()
await writeAndLog(resolve(args.output ?? `export.${ext}`), data)
}
function exportFileName(defaultName: string, extension: string, scale?: number): string {
return scale ? `${defaultName}@${scale}x.${extension}` : `${defaultName}.${extension}`
}
function targetLabel(pageName?: string, nodeId?: string, wholeDocument = false): string {
if (wholeDocument) return 'whole document'
if (nodeId) return `node ${nodeId}`
return pageName ? `page "${pageName}"` : 'first page'
}
type FileExportTarget = { scope: 'node'; nodeId: string } | { scope: 'page'; pageId: string }
/** Writes the export and the files it refers to, which sit next to it. */
async function writeExport(output: string, result: ExportResult) {
await writeAndLog(output, result.data)
const assets = result.assets ?? []
for (const asset of assets) {
const assetPath = join(dirname(output), asset.path)
await mkdir(dirname(assetPath), { recursive: true })
await writeFile(assetPath, asset.content)
}
if (assets.length > 0) console.log(ok(`Assets: ${assets.length} files`))
}
function prepareGraphForExport(
graph: Awaited<ReturnType<typeof loadDocument>>,
pageId: string,
format: string,
args: ExportArgs
): boolean {
const wholeDocument = (format === 'FIG' || format === 'PPTX') && !args.page && !args.node
if (wholeDocument || args.node) populateWholeDocument(graph)
else populateDocumentPage(graph, pageId)
return wholeDocument
}
async function executeFileExport(
formatId: string,
graph: Awaited<ReturnType<typeof loadDocument>>,
target: FileExportTarget,
options: unknown,
wholeDocument: boolean,
fileName: string
) {
if (wholeDocument)
return io.exportContent(formatId, { graph, target: { scope: 'document' }, fileName }, options)
return io.exportContent(formatId, { graph, target, fileName }, options)
}
function exportOptions(format: string, args: ExportArgs): unknown {
if (format === 'FIG') return { renderThumbnail: true }
if (format === 'HTML')
return { html: args.html, style: args.css, assets: args.assets, fonts: args.fonts ?? 'none' }
if (formatSupportsScale(format))
return {
format,
scale: Number(args.scale),
quality: args.quality ? Number(args.quality) : undefined
}
return undefined
}
async function exportFromFile(format: string, args: ExportArgs) {
const file = requireFile(args.file)
const graph = await loadDocument(file)
const pages = graph.getPages()
const page = requirePage(graph, args.page)
const defaultName = basename(file, extname(file))
if (args.page && args.node) {
printError('--page and --node cannot be used together.')
process.exit(1)
}
const wholeDocument = prepareGraphForExport(graph, page.id, format, args)
const target = args.node
? { scope: 'node' as const, nodeId: args.node }
: { scope: 'page' as const, pageId: page.id }
await applyExportFontPolicy(
graph,
exportFontRoots(
args.node,
page.id,
pages.map((candidate) => candidate.id),
wholeDocument
),
format,
args['font-policy']
)
if (args.thumbnail) {
printError('Thumbnail export is not supported by the shared file export path yet.')
process.exit(1)
}
// `--style tailwind` keeps the JSX spelling of the Tailwind JSX format.
const formatId =
format === 'JSX' && args.style === 'tailwind' ? 'tailwind-jsx' : format.toLowerCase()
const scale = formatSupportsScale(format) ? Number(args.scale) : undefined
const extension = io.getFormat(formatId)?.extensions[0] ?? formatId
const output = resolve(args.output ?? exportFileName(defaultName, extension, scale))
const result = await executeFileExport(
formatId,
graph,
target,
exportOptions(format, args),
wholeDocument,
basename(output)
)
await writeExport(output, result)
console.log(ok(`Target: ${targetLabel(args.page, args.node, wholeDocument)}`))
}
export default defineCommand({
meta: { description: `Export a document to ${FORMAT_LIST}` },
args: {
file: {
type: 'positional',
description:
'Document file path (omit to connect to running app); for storybook, several files or a quoted glob',
required: false
},
output: {
type: 'string',
alias: 'o',
description:
'Output file path (default: <name>.<format>); for storybook, a directory (default: <name>-stories)',
required: false
},
format: {
type: 'string',
alias: 'f',
description: `Export format: ${FORMAT_IDS.join(', ')} (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)',
required: false
},
page: {
type: 'string',
description:
'Export a specific page by name (FIG, PPTX, and Storybook default to the whole document)',
required: false
},
node: {
type: 'string',
description: 'Export a specific node by ID (cannot be combined with --page)',
required: false
},
style: {
type: 'string',
description: 'JSX style: openpencil or tailwind (default: openpencil)',
default: 'openpencil'
},
html: {
type: 'string',
description: 'HTML output mode: fragment or standalone (default: fragment)',
default: 'fragment'
},
css: {
type: 'string',
description:
'CSS output: inline or tailwind; for Storybook, how Vue and React components are styled (default: inline)',
default: 'inline'
},
assets: {
type: 'string',
description: 'HTML asset output: inline or external (default: inline)',
default: 'inline'
},
fonts: {
type: 'string',
description:
'HTML and Storybook font files: assets or none (default: none for HTML, assets for Storybook)'
},
framework: {
type: 'string',
description: 'Storybook framework: react, vue, or html (default: react)',
default: 'react'
},
'design-images': {
type: 'boolean',
description: 'Storybook: render each variant to PNG for the Design panel (default: true)',
default: true
},
watch: {
type: 'boolean',
description: 'Storybook: re-export whenever the document changes'
},
beside: {
type: 'boolean',
description: "Storybook: write each document's stories into the document's own folder"
},
rules: {
type: 'string',
description:
'Storybook: rules file for which stories each component gets and its title (default: openpencil.stories.json when present)'
},
'font-policy': {
type: 'string',
description: 'Raster/PDF font policy: warn, strict, or allow (default: warn)',
default: 'warn'
},
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' },
...appTargetOptions
},
async run({ args }) {
const format = args.format.toUpperCase()
if (!ALL_FORMATS.has(format)) {
printError(`Invalid format "${args.format}". Use ${FORMAT_LIST}.`)
process.exit(1)
}
if (format === 'JSX' && !JSX_STYLES.has(args.style)) {
printError(`Invalid JSX style "${args.style}". Use openpencil or tailwind.`)
process.exit(1)
}
if (format === 'HTML' && !HTML_MODES.has(args.html)) {
printError(`Invalid HTML mode "${args.html}". Use fragment or standalone.`)
process.exit(1)
}
if (format === 'HTML' && !HTML_STYLES.has(args.css)) {
printError(`Invalid HTML CSS output "${args.css}". Use inline or tailwind.`)
process.exit(1)
}
if (format === 'HTML' && !HTML_ASSETS.has(args.assets)) {
printError(`Invalid HTML asset output "${args.assets}". Use inline or external.`)
process.exit(1)
}
if (args.fonts && !HTML_FONTS.has(args.fonts)) {
printError(`Invalid font output "${args.fonts}". Use assets or none.`)
process.exit(1)
}
if (!FONT_POLICIES.has(args['font-policy'])) {
printError(`Invalid font policy "${args['font-policy']}". Use warn, strict, or allow.`)
process.exit(1)
}
if (isAppMode(args.file)) {
await exportViaApp(format, args)
} else if (format === 'STORYBOOK') {
await exportStorybookFromFile(args)
} else {
await exportFromFile(format, args)
}
}
})