@openfairygui/cli 0.3.0 → 0.3.1

package/dist/cli.mjs

@@ -745,10 +745,10 @@ var Property = class extends GraphNode {
 		return this.set("name", name);
 	}
 	getExtras() {
-		return this.get("extras");
+		return structuredClone(this.get("extras"));
 	}
 	setExtras(extras) {
-		return this.set("extras", extras);
+		return this.set("extras", structuredClone(extras));
 	}
 	clone() {
 		const PropertyClass = this.constructor;
@@ -829,7 +829,7 @@ var ExtensibleProperty = class extends Property {
 };
 //#endregion
 //#region ../core/src/constants.ts
-const VERSION = `v0.3.0`;
+const VERSION = `v0.3.1`;
 /** Binary package file magic number: "FGUI" as uint32. */
 const FGUI_MAGIC = 1179080009;
 /** Null string index in the binary string table. */
@@ -1219,10 +1219,10 @@ var Root = class extends ExtensibleProperty {
 		return this.setBranches([...this.listBranches(), branch]);
 	}
 	getSettings() {
-		return this.get("settings");
+		return structuredClone(this.get("settings"));
 	}
 	setSettings(settings) {
-		return this.set("settings", settings);
+		return this.set("settings", structuredClone(settings));
 	}
 	/****** Extensions ******/
 	listExtensionsUsed() {
@@ -2263,9 +2263,24 @@ var DragonBonesResource = class extends SkeletonResourceBase {
 * @category Properties
 */
 var Component = class extends ExtensibleProperty {
+	_binaryDirty = true;
 	init() {
 		this.propertyType = PropertyType.COMPONENT;
 	}
+	/** @internal */
+	_markBinaryClean() {
+		this._binaryDirty = false;
+		return this;
+	}
+	/** @internal */
+	_markBinaryDirty() {
+		this._binaryDirty = true;
+		return this;
+	}
+	/** @internal */
+	_isBinaryDirty() {
+		return this._binaryDirty;
+	}
 	getDefaults() {
 		return Object.assign(super.getDefaults(), {
 			id: "",
@@ -15784,7 +15799,6 @@ const { Deflate, deflate, deflateRaw, gzip } = deflate_1$1;
 const { Inflate, inflate, inflateRaw, ungzip } = inflate_1$1;
 var deflateRaw_1 = deflateRaw;
 var Inflate_1 = Inflate;
-var inflateRaw_1 = inflateRaw;
 //#endregion
 //#region ../core/src/utils/image-info.ts
 var import_jpeg_js = require_jpeg_js();
@@ -16180,6 +16194,99 @@ function probeRasterImageDimensions(data) {
 	return readPngInfo(data, false) ?? readJpegInfo(data, false);
 }
 //#endregion
+//#region ../core/src/utils/svg-validation.ts
+const MAX_SVG_SOURCE_BYTES = 8 * 1024 * 1024;
+const MAX_SVG_NODES = 5e4;
+const SVG_NAMESPACE = "http://www.w3.org/2000/svg";
+const XLINK_NAMESPACE = "http://www.w3.org/1999/xlink";
+const UNSAFE_SVG_ELEMENTS = new Set([
+	"a",
+	"animate",
+	"animatecolor",
+	"animatemotion",
+	"animatetransform",
+	"audio",
+	"canvas",
+	"discard",
+	"embed",
+	"feimage",
+	"foreignobject",
+	"iframe",
+	"image",
+	"object",
+	"script",
+	"set",
+	"style",
+	"video"
+]);
+function invalidSvg(message) {
+	throw new Error(`Invalid or unsafe SVG source (${message}).`);
+}
+function validateAttribute(name, value) {
+	const normalizedName = name.toLowerCase();
+	if (normalizedName === "xmlns") {
+		if (value !== SVG_NAMESPACE) invalidSvg("the default namespace must be SVG");
+		return;
+	}
+	if (normalizedName === "xmlns:xlink") {
+		if (value !== XLINK_NAMESPACE) invalidSvg("the xlink namespace is invalid");
+		return;
+	}
+	if (normalizedName.includes(":") && normalizedName !== "xlink:href" && normalizedName !== "xml:space") invalidSvg(`qualified attribute "${name}" is not allowed`);
+	const localName = normalizedName.split(":").at(-1);
+	const text = String(value);
+	if (localName.startsWith("on")) invalidSvg(`event attribute "${name}" is not allowed`);
+	if (localName === "style" || localName === "src") invalidSvg(`attribute "${name}" is not allowed`);
+	if (localName === "href" && !/^#[A-Za-z_][\w:.-]*$/u.test(text)) invalidSvg(`external reference in "${name}" is not allowed`);
+	if (/(?:^|[\s("'=])(?:https?:|file:|javascript:|data:|\/\/)/iu.test(text)) invalidSvg(`external URL in "${name}" is not allowed`);
+	for (const match of text.matchAll(/url\s*\(([^)]*)\)/giu)) {
+		const reference = (match[1] ?? "").trim().replace(/^(['"])(.*)\1$/u, "$2");
+		if (!/^#[A-Za-z_][\w:.-]*$/u.test(reference)) invalidSvg(`external url() in "${name}" is not allowed`);
+	}
+}
+/** Validate SVG bytes before handing them to a host image decoder. */
+function validateSafeSvgSource(bytes) {
+	if (bytes.byteLength === 0 || bytes.byteLength > MAX_SVG_SOURCE_BYTES) invalidSvg("source size is unsupported");
+	let source;
+	try {
+		source = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+	} catch {
+		invalidSvg("source is not valid UTF-8");
+	}
+	if (/<!\s*(?:doctype|entity)\b|<\?xml-stylesheet\b/iu.test(source)) invalidSvg("DTD, entities, and stylesheets are not allowed");
+	if (XMLValidator.validate(source, { allowBooleanAttributes: false }) !== true) invalidSvg("source is not well-formed XML");
+	const roots = new XMLParser({
+		preserveOrder: true,
+		ignoreAttributes: false,
+		attributeNamePrefix: "",
+		parseAttributeValue: false,
+		parseTagValue: false,
+		processEntities: false,
+		trimValues: false
+	}).parse(source).flatMap((entry) => Object.keys(entry).filter((name) => name !== ":@" && !name.startsWith("#") && !name.startsWith("?")).map((name) => ({
+		entry,
+		name
+	})));
+	if (roots.length !== 1 || roots[0].name !== "svg") invalidSvg("a single unqualified <svg> root is required");
+	if (roots[0].entry[":@"]?.xmlns !== SVG_NAMESPACE) invalidSvg("the SVG namespace is required");
+	const pending = [roots[0].entry];
+	let nodeCount = 0;
+	while (pending.length > 0) {
+		const current = pending.pop();
+		for (const [name, value] of Object.entries(current)) {
+			if (name === ":@" || name.startsWith("#") || name.startsWith("?")) continue;
+			if (++nodeCount > MAX_SVG_NODES) invalidSvg("node count exceeds the supported limit");
+			if (name.includes(":")) invalidSvg(`qualified element <${name}> is not allowed`);
+			if (UNSAFE_SVG_ELEMENTS.has(name.toLowerCase())) invalidSvg(`element <${name}> is not allowed`);
+			for (const [attributeName, attributeValue] of Object.entries(current[":@"] ?? {})) validateAttribute(attributeName, attributeValue);
+			if (Array.isArray(value)) {
+				for (const child of value) if (child && typeof child === "object" && !Array.isArray(child)) pending.push(child);
+			}
+		}
+	}
+	return source;
+}
+//#endregion
 //#region ../core/src/document.ts
 /**
 * Wraps a FairyGUI project and its resources for easier modification.
@@ -16206,12 +16313,32 @@ var Document = class Document {
 	_root = new Root(this._graph);
 	_logger = Logger.DEFAULT_INSTANCE;
 	_projectDir = "";
+	_hasBinaryComponents = false;
 	static _GRAPH_DOCUMENTS = /* @__PURE__ */ new WeakMap();
 	static fromGraph(graph) {
 		return Document._GRAPH_DOCUMENTS.get(graph) || null;
 	}
 	constructor() {
 		Document._GRAPH_DOCUMENTS.set(this._graph, this);
+		this._graph.addEventListener("node:change", (event) => {
+			if (!this._hasBinaryComponents) return;
+			const pending = [event.target];
+			const visited = /* @__PURE__ */ new Set();
+			while (pending.length > 0) {
+				const current = pending.pop();
+				if (visited.has(current)) continue;
+				visited.add(current);
+				if (current instanceof Component) {
+					current._markBinaryDirty();
+					continue;
+				}
+				pending.push(...current.listParents());
+			}
+		});
+	}
+	/** @internal */
+	_trackBinaryComponent() {
+		this._hasBinaryComponents = true;
 	}
 	getRoot() {
 		return this._root;
@@ -17212,16 +17339,8 @@ function sourceExtension(resource) {
 }
 function validSvg(bytes) {
 	try {
-		if (bytes.byteLength === 0 || bytes.byteLength > 8 * 1024 * 1024) return false;
-		const source = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
-		if (XMLValidator.validate(source, { allowBooleanAttributes: false }) !== true) return false;
-		if (!/<svg(?:\s|>)/i.test(source)) return false;
-		if (/<!\s*(?:doctype|entity)\b|<\?xml-stylesheet\b/iu.test(source)) return false;
-		if (/<(?:a|animate|animatecolor|animatemotion|animatetransform|audio|canvas|discard|embed|feimage|foreignobject|iframe|image|object|script|set|style|video)(?:\s|>)/iu.test(source)) return false;
-		if (/\s(?:on[\w:-]*|style|src)\s*=/iu.test(source)) return false;
-		if (/\s(?:href|xlink:href)\s*=\s*['"](?!#[A-Za-z_][\w:.-]*['"])/iu.test(source)) return false;
-		const urlSource = source.replace(/\sxmlns\s*=\s*(['"])http:\/\/www\.w3\.org\/2000\/svg\1/giu, "");
-		return !/(?:https?:|file:|javascript:|data:|\/\/)|url\s*\(\s*(?!['"]?#[A-Za-z_])/iu.test(urlSource);
+		validateSafeSvgSource(bytes);
+		return true;
 	} catch {
 		return false;
 	}
@@ -23309,7 +23428,11 @@ var ProjectWriter = class {
 			if (settings[key] === void 0 && await fs.exists(filePath)) staleOptionalSettings.push(filePath);
 		}
 		if (staleOptionalSettings.length > 0 && !fs.unlink) throw new Error("Project settings cleanup requires a FileSystem.unlink() implementation.");
-		const fairyXml = `<?xml version="1.0" encoding="utf-8"?>\n<projectDescription id="${root.getProjectId()}" type="${this._projectTypeName(root.getProjectType())}" version="${root.getVersion() || "3.0"}"/>\n`;
+		const fairyXml = `<?xml version="1.0" encoding="utf-8"?>\n<projectDescription${renderXmlAttrs({
+			id: root.getProjectId(),
+			type: this._projectTypeName(root.getProjectType()),
+			version: root.getVersion() || "3.0"
+		})}/>\n`;
 		await fs.writeFile(projectPath, fairyXml);
 		await fs.mkdir(settingsPath);
 		for (const [fileName, key] of Object.entries({
@@ -24858,6 +24981,41 @@ function decodeComponentDefinition(resource, rawData, extensionTypeCode, doc) {
 }
 //#endregion
 //#region ../core/src/io/binary-reader.ts
+const DEFAULT_BINARY_READ_LIMITS = {
+	maxCompressedBytes: 64 * 1024 * 1024,
+	maxDecompressedBytes: 256 * 1024 * 1024,
+	maxCompressionRatio: 200
+};
+function readLimits(options) {
+	const limits = {
+		...DEFAULT_BINARY_READ_LIMITS,
+		...options.limits
+	};
+	for (const [name, value] of Object.entries(limits)) if (!Number.isFinite(value) || value <= 0) throw new RangeError(`${name} must be a positive finite number.`);
+	return limits;
+}
+function inflateRawWithLimits(input, limits) {
+	if (input.byteLength > limits.maxCompressedBytes) throw new Error(`FairyGUI binary compressed data exceeds ${limits.maxCompressedBytes} bytes.`);
+	const maxOutputBytes = Math.min(limits.maxDecompressedBytes, Math.floor(input.byteLength * limits.maxCompressionRatio));
+	const chunks = [];
+	let outputLength = 0;
+	const inflater = new Inflate_1({ raw: true });
+	inflater.onData = (chunk) => {
+		if (!(chunk instanceof Uint8Array)) throw new Error("FairyGUI binary inflate returned non-binary data.");
+		outputLength += chunk.byteLength;
+		if (outputLength > maxOutputBytes) throw new Error(`FairyGUI binary decompressed data exceeds the configured ${maxOutputBytes} byte budget.`);
+		chunks.push(chunk);
+	};
+	inflater.push(input, true);
+	if (inflater.err !== 0) throw new Error(`Invalid compressed FairyGUI binary data: ${inflater.msg}`);
+	const output = new Uint8Array(outputLength);
+	let offset = 0;
+	for (const chunk of chunks) {
+		output.set(chunk, offset);
+		offset += chunk.byteLength;
+	}
+	return output;
+}
 /**
 * Binary item type codes as used in the .fui format.
 * @internal
@@ -24958,7 +25116,7 @@ function decodeFontGlyphs(doc, resource, buf) {
 	for (let index = 0; index < glyphCount; index += 1) {
 		const chunkSize = buf.getInt16();
 		const nextPos = buf.pos + chunkSize;
-		const charId = buf.getInt16();
+		const charId = buf.getUint16();
 		const glyph = doc.createFontGlyph(`${resource.getId()}_${charId || index}`);
 		glyph.setCharId(charId).setChar(decodeChar(charId)).setImg(buf.readS() ?? "").setX(buf.getInt32()).setY(buf.getInt32()).setXOffset(buf.getInt32()).setYOffset(buf.getInt32()).setWidth(buf.getInt32()).setHeight(buf.getInt32()).setAdvance(buf.getInt32()).setChannel(buf.getUint8());
 		resource.addGlyph(glyph);
@@ -24977,8 +25135,10 @@ function decodeFontGlyphs(doc, resource, buf) {
 */
 var BinaryReader = class {
 	_fs;
-	constructor(fs) {
+	_limits;
+	constructor(fs, options = {}) {
 		this._fs = fs;
+		this._limits = readLimits(options);
 	}
 	async read(filePath) {
 		const doc = new Document();
@@ -25004,9 +25164,12 @@ var BinaryReader = class {
 		outer.skip(20);
 		let buf;
 		if (compressed) {
-			const decompressed = inflateRaw_1(new Uint8Array(outer.buffer, outer.byteOffset + outer.pos, outer.byteLength - outer.pos));
+			const decompressed = inflateRawWithLimits(new Uint8Array(outer.buffer, outer.byteOffset + outer.pos, outer.byteLength - outer.pos), this._limits);
 			buf = new ByteBuffer(decompressed.buffer, 0, decompressed.byteLength);
-		} else buf = outer;
+		} else {
+			if (outer.byteLength - outer.pos > this._limits.maxDecompressedBytes) throw new Error(`FairyGUI binary data exceeds ${this._limits.maxDecompressedBytes} bytes.`);
+			buf = outer;
+		}
 		buf.version = outer.version;
 		const indexTablePos = buf.pos;
 		const ver2 = buf.version >= 2;
@@ -25135,6 +25298,8 @@ var BinaryReader = class {
 						...getComponentExtras(res),
 						_rawBinary: toRawBinarySlice(rawData)
 					});
+					res._markBinaryClean();
+					doc._trackBinaryComponent();
 					pkg.addResource(res);
 					createdResource = res;
 					break;
@@ -25286,7 +25451,7 @@ var BinaryReader = class {
 *
 * @internal
 */
-var WriteBuffer = class {
+var WriteBuffer = class WriteBuffer {
 	_buf;
 	_view;
 	_pos = 0;
@@ -25296,6 +25461,9 @@ var WriteBuffer = class {
 	_strings;
 	/** Raw custom strings written to block 5, keyed by string table index. */
 	_customStrings;
+	static _assertInteger(value, min, max, type) {
+		if (!Number.isSafeInteger(value) || value < min || value > max) throw new RangeError(`${type} value is out of range: ${value}`);
+	}
 	constructor(initialSize = 4096, parent) {
 		this._buf = new ArrayBuffer(initialSize);
 		this._view = new DataView(this._buf);
@@ -25330,34 +25498,41 @@ var WriteBuffer = class {
 		this._view = new DataView(this._buf);
 	}
 	writeUint8(v) {
+		WriteBuffer._assertInteger(v, 0, 255, "uint8");
 		this._ensure(1);
 		this._view.setUint8(this._pos++, v);
 	}
 	writeInt8(v) {
+		WriteBuffer._assertInteger(v, -128, 127, "int8");
 		this._ensure(1);
 		this._view.setInt8(this._pos++, v);
 	}
 	writeUint16(v) {
+		WriteBuffer._assertInteger(v, 0, 65535, "uint16");
 		this._ensure(2);
 		this._view.setUint16(this._pos, v, false);
 		this._pos += 2;
 	}
 	writeInt16(v) {
+		WriteBuffer._assertInteger(v, -32768, 32767, "int16");
 		this._ensure(2);
 		this._view.setInt16(this._pos, v, false);
 		this._pos += 2;
 	}
 	writeUint32(v) {
+		WriteBuffer._assertInteger(v, 0, 4294967295, "uint32");
 		this._ensure(4);
 		this._view.setUint32(this._pos, v, false);
 		this._pos += 4;
 	}
 	writeInt32(v) {
+		WriteBuffer._assertInteger(v, -2147483648, 2147483647, "int32");
 		this._ensure(4);
 		this._view.setInt32(this._pos, v, false);
 		this._pos += 4;
 	}
 	writeFloat32(v) {
+		if (!Number.isFinite(v)) throw new RangeError(`float32 value must be finite: ${v}`);
 		this._ensure(4);
 		this._view.setFloat32(this._pos, v, false);
 		this._pos += 4;
@@ -25368,6 +25543,7 @@ var WriteBuffer = class {
 	/** Write a uint16-prefixed UTF-8 string. */
 	writeUTFString(s) {
 		const encoded = new TextEncoder().encode(s);
+		if (encoded.byteLength > 65535) throw new RangeError(`UTF string exceeds uint16 byte length: ${encoded.byteLength}`);
 		this.writeUint16(encoded.byteLength);
 		this._ensure(encoded.byteLength);
 		new Uint8Array(this._buf, this._pos, encoded.byteLength).set(encoded);
@@ -25394,6 +25570,7 @@ var WriteBuffer = class {
 		const existing = this._stringMap.get(s);
 		if (existing !== void 0) return existing;
 		const index = this._strings.length;
+		if (index >= 65533) throw new RangeError(`String table exceeds protocol index limit: ${index + 1}`);
 		this._strings.push(s);
 		this._stringMap.set(s, index);
 		return index;
@@ -25430,6 +25607,7 @@ var WriteBuffer = class {
 		if (!noCache) this.writeUint16(this.addString(s));
 		else {
 			const index = this._strings.length;
+			if (index >= 65533) throw new RangeError(`String table exceeds protocol index limit: ${index + 1}`);
 			this._strings.push(s);
 			this.writeUint16(index);
 		}
@@ -27236,7 +27414,7 @@ var BinaryWriter = class {
 					const compExtras = res.getExtras();
 					const extType = res.getExtensionType?.() ?? compExtras.extensionType;
 					data.writeUint8(extType ? extTypeMap[extType] ?? 0 : 0);
-					if (compExtras?._rawBinary) data.writeBuffer(toUint8Array(compExtras._rawBinary));
+					if (compExtras?._rawBinary && !res._isBinaryDirty()) data.writeBuffer(toUint8Array(compExtras._rawBinary));
 					else {
 						const encoded = encodeComponent(res, doc, pkg, version, data);
 						data.writeBuffer(encoded);
@@ -27525,7 +27703,7 @@ function _encodeFontGlyphs(fntData, parentBuf) {
 	for (const glyph of fntData.glyphs) {
 		const glyphStart = buf.pos;
 		buf.writeInt16(0);
-		buf.writeInt16(glyph.charId);
+		buf.writeUint16(glyph.charId);
 		buf.writeS(glyph.img);
 		buf.writeInt32(glyph.x);
 		buf.writeInt32(glyph.y);
@@ -27659,8 +27837,8 @@ var PlatformIO = class {
 	async writeProject(doc, projectPath, options) {
 		return new ProjectWriter(this.createFileSystem()).write(doc, projectPath, options);
 	}
-	async readBinary(filePath) {
-		return new BinaryReader(this.createFileSystem()).read(filePath);
+	async readBinary(filePath, options) {
+		return new BinaryReader(this.createFileSystem(), options).read(filePath);
 	}
 	async writeBinary(doc, filePath, options) {
 		return new BinaryWriter(this.createFileSystem()).write(doc, filePath, options);
@@ -30107,6 +30285,9 @@ const FGUI_TYPESCRIPT_BINDER_TEMPLATE = `{{generatedMark}}
 function formatPluginError(error) {
 	return error instanceof Error ? error.message : String(error);
 }
+function shouldAbortPluginFailure(plugin) {
+	return plugin.failureMode !== "warn";
+}
 //#endregion
 //#region ../functions/src/path-utils.ts
 function trimTrailingSlashes(value) {
@@ -30192,7 +30373,9 @@ async function publishCodeGeneration(doc, options) {
 				handled = true;
 				logger.info(`publish: Generated code using plugin "${plugin.name}"`);
 			} catch (error) {
-				logger.warn(`publish: Code generation plugin "${plugin.name}" failed: ${formatPluginError(error)}`);
+				const message = `publish: Code generation plugin "${plugin.name}" failed: ${formatPluginError(error)}`;
+				if (shouldAbortPluginFailure(plugin)) throw new Error(message);
+				logger.warn(message);
 			}
 		}
 		if (handled) return;
@@ -31574,7 +31757,9 @@ async function runPublishPluginHook(plugins, hook, doc, options) {
 		try {
 			await fn(doc, options);
 		} catch (error) {
-			logger.warn(`publish: Plugin "${plugin.name}" ${hook} failed: ${formatPluginError(error)}`);
+			const message = `publish: Plugin "${plugin.name}" ${hook} failed: ${formatPluginError(error)}`;
+			if (shouldAbortPluginFailure(plugin)) throw new Error(message);
+			logger.warn(message);
 		}
 	}
 }
@@ -31866,15 +32051,9 @@ var NodeIO = class extends PlatformIO {
 			},
 			async readdir(dirPath) {
 				const entries = await fs$1.readdir(dirPath, { withFileTypes: true });
-				return (await Promise.all(entries.map(async (entry) => {
-					if (entry.isDirectory()) return entry.name;
-					if (!entry.isSymbolicLink()) return null;
-					try {
-						return (await fs$1.stat(path$1.join(dirPath, entry.name))).isDirectory() ? entry.name : null;
-					} catch {
-						return null;
-					}
-				}))).filter((entry) => entry !== null);
+				const symlink = entries.find((entry) => entry.isSymbolicLink());
+				if (symlink) throw new Error(`Symbolic links are not supported in project directories: ${path$1.join(dirPath, symlink.name)}`);
+				return entries.filter((entry) => entry.isDirectory()).map((entry) => entry.name);
 			},
 			async exists(filePath) {
 				try {
@@ -31959,16 +32138,33 @@ async function loadPlugins(doc, pluginsDir) {
 	for (const entry of entries) {
 		if (!entry.isDirectory()) continue;
 		const pluginDir = path.join(pluginsDir, entry.name);
+		let manifest;
+		try {
+			manifest = await readPluginManifest(fs, path, pluginDir);
+		} catch (error) {
+			doc.getLogger().warn(`publish: Plugin "${entry.name}" was skipped: ${formatPluginError(error)}`);
+			continue;
+		}
+		if (!manifest) continue;
+		if (!manifest.main) {
+			const error = /* @__PURE__ */ new Error(`Codegen plugin "${manifest.name}" is missing package.json main.`);
+			if (manifest.required) throw error;
+			doc.getLogger().warn(`publish: Plugin "${manifest.name}" was skipped: ${error.message}`);
+			continue;
+		}
 		try {
-			const manifest = await readPluginManifest(fs, path, pluginDir);
-			if (!manifest) continue;
 			const plugin = await loadPlugin(resolvePluginMain(path, pluginDir, manifest));
 			plugins.push({
 				name: manifest.name,
-				plugin
+				plugin,
+				failureMode: manifest.required ? "abort" : manifest.failureMode
 			});
 		} catch (error) {
-			doc.getLogger().warn(`publish: Plugin "${entry.name}" was skipped: ${formatPluginError(error)}`);
+			if (!manifest.required && manifest.failureMode === "warn") {
+				doc.getLogger().warn(`publish: Plugin "${manifest.name}" was skipped: ${formatPluginError(error)}`);
+				continue;
+			}
+			throw new Error(`publish: Failed to load plugin "${manifest.name}": ${formatPluginError(error)}`);
 		}
 	}
 	return plugins;
@@ -31978,7 +32174,6 @@ async function readPluginManifest(fs, path, pluginDir) {
 	const content = await fs.readFile(manifestPath, "utf-8");
 	const manifest = JSON.parse(content);
 	if (!manifest.name) throw new Error(`Codegen plugin at ${pluginDir} is missing package.json name.`);
-	if (!manifest.main) throw new Error(`Codegen plugin "${manifest.name}" is missing package.json main.`);
 	return manifest;
 }
 function resolvePluginMain(path, pluginDir, manifest) {
@@ -32043,6 +32238,77 @@ async function loadNodePublishPlugins(document, assetsPath) {
 	if (!projectDir) return [];
 	return loadPlugins(document, (await importNative$2("node:path")).join(projectDir, "plugins"));
 }
+async function publishToStagedOutput(output, run) {
+	const [fs, path, { randomUUID }] = await Promise.all([
+		importNative$2("node:fs/promises"),
+		importNative$2("node:path"),
+		importNative$2("node:crypto")
+	]);
+	const target = path.resolve(output);
+	const parent = path.dirname(target);
+	const name = path.basename(target);
+	const staging = path.join(parent, `.${name}.publish-${randomUUID()}`);
+	const backup = path.join(parent, `.${name}.publish-backup-${randomUUID()}`);
+	await fs.mkdir(parent, { recursive: true });
+	let existed = false;
+	try {
+		const stat = await fs.lstat(target);
+		if (stat.isSymbolicLink() || !stat.isDirectory()) throw new Error(`publishNode: output must be a regular directory: ${target}`);
+		await assertNoSymlinks(fs, path, target);
+		existed = true;
+	} catch (error) {
+		if (error.code !== "ENOENT") throw error;
+	}
+	try {
+		if (existed) await fs.cp(target, staging, {
+			recursive: true,
+			errorOnExist: true,
+			force: false
+		});
+		else await fs.mkdir(staging);
+	} catch (error) {
+		await fs.rm(staging, {
+			recursive: true,
+			force: true
+		});
+		throw error;
+	}
+	try {
+		await run(staging);
+	} catch (error) {
+		await fs.rm(staging, {
+			recursive: true,
+			force: true
+		});
+		throw error;
+	}
+	if (!existed) {
+		await fs.rename(staging, target);
+		return;
+	}
+	await fs.rename(target, backup);
+	try {
+		await fs.rename(staging, target);
+	} catch (error) {
+		await fs.rename(backup, target);
+		await fs.rm(staging, {
+			recursive: true,
+			force: true
+		});
+		throw error;
+	}
+	await fs.rm(backup, {
+		recursive: true,
+		force: true
+	}).catch(() => void 0);
+}
+async function assertNoSymlinks(fs, path, directory) {
+	for (const entry of await fs.readdir(directory, { withFileTypes: true })) {
+		const entryPath = path.join(directory, entry.name);
+		if (entry.isSymbolicLink()) throw new Error(`publishNode: symbolic links are not supported in output directories: ${entryPath}`);
+		if (entry.isDirectory()) await assertNoSymlinks(fs, path, entryPath);
+	}
+}
 /**
 * Publish a FairyGUI project through the standard Node host adapter.
 *
@@ -32055,17 +32321,25 @@ async function publishNode(options) {
 	const [fileSystem, assetsPath] = await Promise.all([createNodePublishFileSystem(), resolveNodeAssetsPath(document, configuredAssetsPath)]);
 	const [encoder, plugins] = await Promise.all([configuredEncoder === void 0 ? loadSharpBackend() : Promise.resolve(configuredEncoder), configuredPlugins === void 0 ? loadNodePublishPlugins(document, assetsPath) : Promise.resolve(configuredPlugins)]);
 	if (!encoder) throw new Error("publishNode: Sharp is required for a complete publish. Install sharp or provide an encoder.");
-	await document.transform(publish({
-		...publishOptions,
-		basePath: assetsPath,
-		encoder,
-		atlas: {
-			...atlas,
-			readFileRaw: fileSystem.readFileRaw
-		},
-		fs: fileSystem,
-		plugins
-	}));
+	const run = async (output) => {
+		await document.transform(publish({
+			...publishOptions,
+			output,
+			basePath: assetsPath,
+			encoder,
+			atlas: {
+				...atlas,
+				readFileRaw: fileSystem.readFileRaw
+			},
+			fs: fileSystem,
+			plugins
+		}));
+	};
+	if (publishOptions.output) {
+		await publishToStagedOutput(publishOptions.output, run);
+		return;
+	}
+	await run(void 0);
 }
 //#endregion
 //#region ../functions/src/adapters/node/restore.ts
@@ -32364,7 +32638,7 @@ function registerValidateCommand(program) {
 //#region src/utils/package-version.ts
 const require$1 = createRequire(import.meta.url);
 function getInjectedPackageVersion() {
-	const version = "0.3.0";
+	const version = "0.3.1";
 	return typeof version === "string" && true ? version : null;
 }
 function readPackageVersion() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openfairygui/cli",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "FairyGUI Headless Authoring SDK — command-line interface.",
   "author": "OpenFairyGUI Contributors",
   "license": "MIT",
@@ -13,6 +13,9 @@
   "bugs": {
     "url": "https://github.com/OpenFairyGUI/OpenFairyGUI/issues"
   },
+  "engines": {
+    "node": ">=20"
+  },
   "type": "module",
   "bin": {
     "ofgui": "bin/cli.cjs",
@@ -33,13 +36,13 @@
     "restore"
   ],
   "devDependencies": {
-    "@openfairygui/core": "0.3.0",
-    "@openfairygui/functions": "0.3.0"
+    "@openfairygui/functions": "0.3.1",
+    "@openfairygui/core": "0.3.1"
   },
   "dependencies": {
     "commander": "^14.0.2",
     "jiti": "^2.7.0",
-    "@openfairygui/backend": "0.3.0"
+    "@openfairygui/backend": "0.3.1"
   },
   "optionalDependencies": {
     "sharp": ">=0.33.0"