@openfairygui/cli 0.2.0-alpha.13 → 0.2.0-alpha.15

package/README.md

@@ -14,9 +14,12 @@ npm install --global @openfairygui/cli
 ofgui --help
 ofgui inspect ./MyProject
 ofgui publish ./MyProject --output ./release
+# Trusted-local recovery only; this is not a normal authoring workflow.
 ofgui restore ./release --output ./restored-project
 ```
 
+`restore` accepts a publish directory and writes a new project directory. It validates artifact paths and completes a staged write before `--force` replaces an existing output; it does not make untrusted artifacts safe or recover the original source project.
+
 The package also keeps `openfairygui` as a compatibility alias for the CLI command.
 
 Repository:

package/dist/cli.mjs

@@ -1549,6 +1549,13 @@ var ImageResource = class extends ExtensibleProperty {
 	setImageData(buffer) {
 		return this.setRef("imageData", buffer);
 	}
+	/** Primary source-file bytes for this image resource. */
+	getSourceData() {
+		return this.getImageData();
+	}
+	setSourceData(buffer) {
+		return this.setImageData(buffer);
+	}
 	getPixelHitTestData() {
 		const pixelWidth = this.get("pixelHitTestPixelWidth");
 		const scaleDenominator = this.get("pixelHitTestScaleDenominator");
@@ -1634,6 +1641,13 @@ var MiscResource = class extends ExtensibleProperty {
 	setResourceData(buffer) {
 		return this.setRef("resourceData", buffer);
 	}
+	/** Primary source-file bytes for this miscellaneous resource. */
+	getSourceData() {
+		return this.getResourceData();
+	}
+	setSourceData(buffer) {
+		return this.setResourceData(buffer);
+	}
 };
 //#endregion
 //#region ../core/src/properties/sound-resource.ts
@@ -1698,6 +1712,13 @@ var SoundResource = class extends ExtensibleProperty {
 	setSoundData(buffer) {
 		return this.setRef("soundData", buffer);
 	}
+	/** Primary source-file bytes for this sound resource. */
+	getSourceData() {
+		return this.getSoundData();
+	}
+	setSourceData(buffer) {
+		return this.setSoundData(buffer);
+	}
 };
 //#endregion
 //#region ../core/src/properties/font-resource.ts
@@ -1727,7 +1748,8 @@ var FontResource = class extends ExtensibleProperty {
 			fontSize: 0,
 			xAdvance: 0,
 			lineHeight: 0,
-			glyphs: new RefList()
+			glyphs: new RefList(),
+			sourceData: null
 		});
 	}
 	getId() {
@@ -1835,6 +1857,13 @@ var FontResource = class extends ExtensibleProperty {
 	listGlyphs() {
 		return this.listRefs("glyphs");
 	}
+	/** Primary source-file bytes for this font resource. */
+	getSourceData() {
+		return this.getRef("sourceData");
+	}
+	setSourceData(buffer) {
+		return this.setRef("sourceData", buffer);
+	}
 };
 //#endregion
 //#region ../core/src/properties/movie-clip-resource.ts
@@ -1862,7 +1891,8 @@ var MovieClipResource = class extends ExtensibleProperty {
 			swing: false,
 			repeatDelay: 0,
 			smoothing: true,
-			frames: new RefList()
+			frames: new RefList(),
+			sourceData: null
 		});
 	}
 	getId() {
@@ -1958,6 +1988,13 @@ var MovieClipResource = class extends ExtensibleProperty {
 	listFrames() {
 		return this.listRefs("frames");
 	}
+	/** Primary source-file bytes for this movie-clip resource. */
+	getSourceData() {
+		return this.getRef("sourceData");
+	}
+	setSourceData(buffer) {
+		return this.setRef("sourceData", buffer);
+	}
 };
 //#endregion
 //#region ../core/src/properties/skeleton-resource-base.ts
@@ -1979,7 +2016,8 @@ var SkeletonResourceBase = class extends ExtensibleProperty {
 			requireIds: [],
 			atlasNames: [],
 			anchorX: 0,
-			anchorY: 0
+			anchorY: 0,
+			sourceData: null
 		});
 	}
 	getId() {
@@ -2058,6 +2096,13 @@ var SkeletonResourceBase = class extends ExtensibleProperty {
 		this.setAnchorX(x);
 		return this.setAnchorY(y);
 	}
+	/** Primary source-file bytes for this skeleton resource. */
+	getSourceData() {
+		return this.getRef("sourceData");
+	}
+	setSourceData(buffer) {
+		return this.setRef("sourceData", buffer);
+	}
 };
 //#endregion
 //#region ../core/src/properties/spine-resource.ts
@@ -10375,7 +10420,7 @@ var ProjectReader = class {
 	constructor(fs) {
 		this._fs = fs;
 	}
-	async read(projectPath) {
+	async read(projectPath, options = {}) {
 		const fs = this._fs;
 		const doc = new Document();
 		const basePath = getProjectBasePath(fs, projectPath);
@@ -10399,9 +10444,9 @@ var ProjectReader = class {
 		for (const dirName of packageDirs) {
 			const pkgXmlPath = fs.join(assetsPath, dirName, "package.xml");
 			if (!await fs.exists(pkgXmlPath)) continue;
-			await this._readPackage(ctx, dirName, pkgXmlPath);
+			await this._readPackage(ctx, dirName, pkgXmlPath, "", options);
 		}
-		const branchNames = await this._readPackageBranches(ctx);
+		const branchNames = await this._readPackageBranches(ctx, options);
 		if (branchNames.length > 0) doc.getRoot().setBranches(branchNames);
 		for (const [_key, resource] of ctx.resourceMap) {
 			if (resource.propertyType !== "Component") continue;
@@ -10417,7 +10462,7 @@ var ProjectReader = class {
 		}
 		return doc;
 	}
-	async _readPackageBranches(ctx) {
+	async _readPackageBranches(ctx, options) {
 		const fs = this._fs;
 		let dirNames = [];
 		try {
@@ -10437,7 +10482,7 @@ var ProjectReader = class {
 			for (const dirName of packageDirs) {
 				const pkgXmlPath = fs.join(branchAssetsPath, dirName, "package_branch.xml");
 				if (!await fs.exists(pkgXmlPath)) continue;
-				await this._readPackage(ctx, dirName, pkgXmlPath, branchName);
+				await this._readPackage(ctx, dirName, pkgXmlPath, branchName, options);
 			}
 		}
 		return branchNames;
@@ -10475,7 +10520,7 @@ var ProjectReader = class {
 		} catch {}
 		ctx.document.getRoot().setSettings(ctx.settings);
 	}
-	async _readPackage(ctx, dirName, pkgXmlPath, branchName = "") {
+	async _readPackage(ctx, dirName, pkgXmlPath, branchName = "", options = {}) {
 		const fs = this._fs;
 		const content = await fs.readFile(pkgXmlPath);
 		const xml = parseXML(content);
@@ -10513,6 +10558,7 @@ var ProjectReader = class {
 				if (resource) createdResources.push(resource);
 			}
 			await this._hydratePackageImageSizes(createdResources, packageDir);
+			if (options.hydrateResourceBytes) await this._hydratePackageResourceBytes(ctx.document, createdResources, packageDir);
 			return;
 		}
 		for (const tagName of [
@@ -10521,6 +10567,8 @@ var ProjectReader = class {
 			"font",
 			"sound",
 			"movieclip",
+			"spine",
+			"dragonbones",
 			"swf",
 			"misc",
 			"atlas"
@@ -10534,6 +10582,7 @@ var ProjectReader = class {
 			}
 		}
 		await this._hydratePackageImageSizes(createdResources, packageDir);
+		if (options.hydrateResourceBytes) await this._hydratePackageResourceBytes(ctx.document, createdResources, packageDir);
 	}
 	async _hydratePackageImageSizes(resources, packageDir) {
 		const fs = this._fs;
@@ -10544,7 +10593,9 @@ var ProjectReader = class {
 			const fileName = image.getFileName?.() ?? "";
 			if (!fileName) continue;
 			const resourcePath = image.getPath?.() ?? "/";
-			const filePath = fs.join(packageDir, resourcePath.replace(/^\//, ""), fileName);
+			const sourcePath = this._packageRelativeSourcePath(resourcePath, fileName);
+			if (!sourcePath) continue;
+			const filePath = fs.join(packageDir, sourcePath.replace(/^\/+/, ""));
 			if (!await fs.exists(filePath)) continue;
 			try {
 				const size = readImageSize(await fs.readFileRaw(filePath));
@@ -10554,6 +10605,44 @@ var ProjectReader = class {
 			} catch {}
 		}
 	}
+	async _hydratePackageResourceBytes(doc, resources, packageDir) {
+		const fs = this._fs;
+		for (const resource of resources) {
+			const fileName = this._primaryResourceFileName(resource);
+			if (!fileName) continue;
+			const resourcePath = resource.getPath?.() ?? "/";
+			const sourcePath = this._packageRelativeSourcePath(resourcePath, fileName);
+			if (!sourcePath) continue;
+			const filePath = fs.join(packageDir, sourcePath.replace(/^\/+/, ""));
+			if (!await fs.exists(filePath)) continue;
+			try {
+				const data = new Uint8Array(await fs.readFileRaw(filePath));
+				const buffer = doc.createBuffer().setURI(sourcePath).setData(data);
+				this._asSourceDataResource(resource).setSourceData(buffer);
+			} catch {}
+		}
+	}
+	_primaryResourceFileName(resource) {
+		switch (resource.propertyType) {
+			case "ImageResource":
+			case "FontResource":
+			case "MovieClipResource": return resource.getFileName();
+			case "SoundResource":
+			case "MiscResource":
+			case "SpineResource":
+			case "DragonBonesResource": return resource.getFile();
+			default: return "";
+		}
+	}
+	_packageRelativeSourcePath(resourcePath, fileName) {
+		if (!fileName || /[\\/:]/.test(fileName) || fileName === "." || fileName === "..") return null;
+		const segments = resourcePath.replace(/\\/g, "/").split("/").filter(Boolean);
+		if (segments.some((segment) => segment === "." || segment === ".." || segment.includes(":"))) return null;
+		return `/${[...segments, fileName].join("/")}`;
+	}
+	_asSourceDataResource(resource) {
+		return resource;
+	}
 	_createResourceFromXML(ctx, pkg, tagName, attrs, packageDir, branchName = "") {
 		const doc = ctx.document;
 		const fs = this._fs;
@@ -12425,21 +12514,18 @@ function assertDisplayListVariantAllowed(propertyType, tagName, childName) {
 	const variantName = getDisplayListVariantName(propertyType, tagName);
 	if (!DISPLAY_LIST_ALLOWED_VARIANTS.has(variantName)) throw new Error(`displayList variant "${variantName}" derived from propertyType "${propertyType}" is not declared in protocol for child "${childName}"`);
 }
-/**
-* Writes a {@link Document} to disk as a FairyGUI project
-* (.fairy file + settings JSON + assets directory with package.xml and component XML files).
-*
-* @category I/O
-*/
 var ProjectWriter = class {
 	_fs;
 	constructor(fs) {
 		this._fs = fs;
 	}
-	async write(doc, projectPath) {
+	async write(doc, projectPath, options = {}) {
 		const fs = this._fs;
 		const root = doc.getRoot();
 		const basePath = fs.dirname(projectPath);
+		const currentSourceFilePaths = /* @__PURE__ */ new Set();
+		const staleSourceFilePaths = new Set((options.staleSourceFiles ?? []).map((source) => this._projectSourceFilePath(basePath, source)));
+		for (const pkg of root.listPackages()) this._assertPackageOutputTargets(pkg);
 		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`;
 		await fs.writeFile(projectPath, fairyXml);
 		const settings = root.getSettings?.() ?? {};
@@ -12452,10 +12538,12 @@ var ProjectWriter = class {
 		})) if (settings[key]) await fs.writeFile(fs.join(settingsPath, fileName), JSON.stringify(settings[key], null, "	"));
 		const assetsPath = fs.join(basePath, "assets");
 		await fs.mkdir(assetsPath);
-		for (const pkg of root.listPackages()) await this._writePackage(doc, pkg, assetsPath);
+		for (const pkg of root.listPackages()) await this._writePackage(doc, pkg, assetsPath, currentSourceFilePaths);
+		await this._removeStaleSourceFiles(currentSourceFilePaths, staleSourceFilePaths);
 	}
-	async _writePackage(_doc, pkg, assetsPath) {
+	async _writePackage(_doc, pkg, assetsPath, currentSourceFilePaths) {
 		const fs = this._fs;
+		this._assertSafePathSegment(pkg.getName(), "package name");
 		const pkgDir = fs.join(assetsPath, pkg.getName());
 		await fs.mkdir(pkgDir);
 		const basePath = fs.dirname(assetsPath);
@@ -12496,13 +12584,93 @@ var ProjectWriter = class {
 		if (publishAtlases.length > 0) publishAttrs.atlas = publishAtlases;
 		await fs.writeFile(fs.join(pkgDir, "package.xml"), this._renderPackageDescriptionXml(packageDescriptionAttrs, mainResources, publishAttrs));
 		for (const comp of mainResources.filter((resource) => resource.propertyType === "Component")) await this._writeComponent(comp, pkgDir);
+		await this._writeResourceSourceFiles(mainResources, pkgDir, currentSourceFilePaths);
 		for (const [branchName, branchResources] of resourcesByBranch) {
 			if (!branchName) continue;
+			this._assertSafePathSegment(branchName, "branch name");
 			const branchPkgDir = fs.join(basePath, `assets_${branchName}`, pkg.getName());
 			await fs.mkdir(branchPkgDir);
 			await fs.writeFile(fs.join(branchPkgDir, "package_branch.xml"), this._renderBranchDescriptionXml(branchResources));
 			for (const comp of branchResources.filter((resource) => resource.propertyType === "Component")) await this._writeComponent(comp, branchPkgDir);
+			await this._writeResourceSourceFiles(branchResources, branchPkgDir, currentSourceFilePaths);
+		}
+	}
+	async _writeResourceSourceFiles(resources, packageDir, currentSourceFilePaths) {
+		const fs = this._fs;
+		for (const resource of resources) {
+			if (resource.propertyType === "Component") continue;
+			const fileName = this._resourceFileName(resource);
+			if (!fileName) continue;
+			const relativePath = this._resourceSourceRelativePath(resource, fileName);
+			const targetPath = fs.join(packageDir, relativePath);
+			currentSourceFilePaths.add(targetPath);
+			const sourceData = resource.getSourceData?.();
+			if (!sourceData) continue;
+			const data = sourceData.getData();
+			if (!data) continue;
+			await fs.mkdir(fs.dirname(targetPath));
+			await fs.writeFileRaw(targetPath, new Uint8Array(data));
+		}
+	}
+	async _removeStaleSourceFiles(currentSourceFilePaths, staleSourceFilePaths) {
+		const fs = this._fs;
+		const candidates = [...staleSourceFilePaths].filter((filePath) => !currentSourceFilePaths.has(filePath));
+		if (candidates.length === 0) return;
+		if (!fs.unlink) throw new Error("Project source cleanup requires a FileSystem.unlink() implementation.");
+		for (const filePath of candidates) {
+			if (!await fs.exists(filePath)) continue;
+			await fs.unlink(filePath);
+		}
+	}
+	_assertPackageOutputTargets(pkg) {
+		this._assertSafePathSegment(pkg.getName(), "package name");
+		const resourcesByBranch = /* @__PURE__ */ new Map();
+		for (const resource of pkg.listResources()) {
+			const branchName = resource.getBranch?.() ?? "";
+			const bucket = resourcesByBranch.get(branchName) ?? [];
+			bucket.push(resource);
+			resourcesByBranch.set(branchName, bucket);
 		}
+		for (const [branchName, resources] of resourcesByBranch) {
+			if (branchName) this._assertSafePathSegment(branchName, "branch name");
+			const targets = new Map([[branchName ? "package_branch.xml" : "package.xml", "package descriptor"]]);
+			for (const resource of resources) {
+				const target = resource.propertyType === "Component" ? this._componentSourceRelativePath(resource) : this._resourceSourceRelativePath(resource, this._resourceFileName(resource));
+				if (!target) continue;
+				const previous = targets.get(target);
+				if (previous) throw new Error(`Package "${pkg.getName()}" output "${target}" conflicts with ${previous}.`);
+				targets.set(target, `resource "${resource.getId?.() ?? resource.getName()}"`);
+			}
+		}
+	}
+	_projectSourceFilePath(basePath, source) {
+		this._assertSafePathSegment(source.packageName, "stale source package name");
+		if (source.branch) this._assertSafePathSegment(source.branch, "stale source branch name");
+		this._assertSafePathSegment(source.fileName, "stale source file name");
+		const relativePath = this._normalizeSourceRelativePath([source.path, source.fileName].filter(Boolean).join("/"));
+		const assetRoot = source.branch ? `assets_${source.branch}` : "assets";
+		return this._fs.join(basePath, assetRoot, source.packageName, relativePath);
+	}
+	_resourceSourceRelativePath(resource, fileName) {
+		if (!fileName) return "";
+		this._assertSafePathSegment(fileName, "resource file name");
+		const normalizedPath = (resource.getPath?.() ?? "/").replace(/\\/g, "/").replace(/^\/+|\/+$/g, "");
+		return this._normalizeSourceRelativePath([normalizedPath, fileName].filter(Boolean).join("/"));
+	}
+	_componentSourceRelativePath(component) {
+		const typedComponent = component;
+		const name = component.getName();
+		this._assertSafePathSegment(name, "component name");
+		const componentPath = typedComponent.getPath?.() ?? "/";
+		return this._normalizeSourceRelativePath([componentPath, `${name}.xml`].filter(Boolean).join("/"));
+	}
+	_assertSafePathSegment(value, label) {
+		if (!value || value === "." || value === ".." || /[\\/:]/.test(value)) throw new Error(`Invalid ${label} "${value}".`);
+	}
+	_normalizeSourceRelativePath(value) {
+		const segments = value.replace(/\\/g, "/").split("/").filter(Boolean);
+		if (segments.some((segment) => segment === "." || segment === ".." || segment.includes(":"))) throw new Error(`Invalid project source path "${value}".`);
+		return segments.join("/");
 	}
 	_renderPackageDescriptionXml(packageDescriptionAttrs, resources, publishAttrs) {
 		const publishNodeAttrs = Object.fromEntries(Object.entries(publishAttrs).filter(([key]) => key !== "atlas"));
@@ -12647,11 +12815,8 @@ var ProjectWriter = class {
 	async _writeComponent(comp, pkgDir) {
 		const fs = this._fs;
 		const typedComp = comp;
-		const path = typedComp.getPath?.() ?? "/";
-		const name = comp.getName() + ".xml";
-		const subDir = path.replace(/^\//, "").replace(/\/$/, "");
-		const fileDir = subDir ? fs.join(pkgDir, subDir) : pkgDir;
-		if (subDir) await fs.mkdir(fileDir);
+		const targetPath = fs.join(pkgDir, this._componentSourceRelativePath(comp));
+		await fs.mkdir(fs.dirname(targetPath));
 		const compAttrs = {};
 		const [w, h] = [typedComp.getWidth?.() ?? 0, typedComp.getHeight?.() ?? 0];
 		if (w || h) writeXmlAttr(compAttrs, PROJECT_XML_PROTOCOL.componentRoot.attrs.size, `${w},${h}`);
@@ -12793,7 +12958,7 @@ var ProjectWriter = class {
 			},
 			component: compNode
 		};
-		await fs.writeFile(fs.join(fileDir, name), builder.build(xmlObj));
+		await fs.writeFile(targetPath, builder.build(xmlObj));
 	}
 	_serializeController(ctrl) {
 		const pagesStr = ctrl.listPages().map((p) => `${p.getId()},${p.getName()}`).join(",");
@@ -21033,11 +21198,11 @@ function getPixelHitTestEntry(resource) {
 * @category I/O
 */
 var PlatformIO = class {
-	async readProject(projectPath) {
-		return new ProjectReader(this.createFileSystem()).read(projectPath);
+	async readProject(projectPath, options) {
+		return new ProjectReader(this.createFileSystem()).read(projectPath, options);
 	}
-	async writeProject(doc, projectPath) {
-		return new ProjectWriter(this.createFileSystem()).write(doc, projectPath);
+	async writeProject(doc, projectPath, options) {
+		return new ProjectWriter(this.createFileSystem()).write(doc, projectPath, options);
 	}
 	async readBinary(filePath) {
 		return new BinaryReader(this.createFileSystem()).read(filePath);
@@ -21756,7 +21921,8 @@ const ATLAS_DEFAULTS = {
 	preserveInputOrderOnTie: false,
 	directSingleImageOutput: false,
 	extractAlpha: false,
-	separatedAtlasForBranch: false
+	separatedAtlasForBranch: false,
+	strictOutput: false
 };
 function getPublishedItemId(resource) {
 	return (resource.getExtras() ?? {})._publishedId ?? resource.getId();
@@ -21913,8 +22079,9 @@ function atlas(_options = {}) {
 		const packageFilter = options.packages ? new Set(options.packages) : null;
 		for (const pkg of root.listPackages()) {
 			if (packageFilter && !packageFilter.has(pkg.getName())) continue;
-			const selectedPublishIds = new Set((pkg.getExtras() ?? {}).publishedResourceIds ?? []);
-			const allResources = selectedPublishIds.size > 0 ? pkg.listResources().filter((resource) => selectedPublishIds.has(resource.getId())) : pkg.listResources();
+			const publishedResourceIds = pkg.getExtras()?.publishedResourceIds;
+			const selectedPublishIds = new Set(publishedResourceIds);
+			const allResources = publishedResourceIds !== void 0 && (options.strictOutput || selectedPublishIds.size > 0) ? pkg.listResources().filter((resource) => selectedPublishIds.has(resource.getId())) : pkg.listResources();
 			const skeletonDependencyImageIds = getSelectedSkeletonDependencyImageIds(allResources);
 			const orderedResources = await resolveEditorCompatibleResourceOrder(pkg, allResources, options);
 			const orderedAllResources = sortResourcesByOrder(allResources, new Map(orderedResources.map((resource, index) => [resource.getId(), index])), new Map(allResources.map((resource, index) => [resource.getId(), index])));
@@ -22003,6 +22170,7 @@ function atlas(_options = {}) {
 				await _collectFontTexture(doc, res, pkg, options);
 			}
 			if (inputs.length === 0) continue;
+			if (options.strictOutput && (!encoder || !options.basePath || !options.outputPath)) throw new Error(`atlas: Package "${pkg.getName()}" requires encoder, basePath, and outputPath for complete raster output.`);
 			let totalPageCount = 0;
 			let usedDirectOutput = false;
 			const { autoInputs, fixedPageGroups, standaloneGroups, reservedPageIndexes } = groupStandaloneInputs(doc, inputs, options);
@@ -22100,7 +22268,7 @@ function reserveAutoPageStart(branchPageOffsets, branchOrdinal, reservedPageInde
 async function emitPagedAtlasGroup(doc, pkg, allResources, inputs, context) {
 	if (inputs.length === 0) return 0;
 	const pages = packAtlasPages(inputs, context.options, context.forceSinglePage === true);
-	if (pages.length === 0) return 0;
+	assertPackedInputCoverage(pages, inputs.length, `package "${pkg.getName()}"`);
 	for (let pageOffset = 0; pageOffset < pages.length; pageOffset += 1) {
 		const page = pages[pageOffset];
 		const pageIndex = context.pageStart + pageOffset;
@@ -22126,7 +22294,7 @@ async function emitStandaloneAtlasGroup(doc, pkg, group, context) {
 		multipleOfFour: true,
 		square: false
 	} : void 0);
-	if (pages.length === 0) return 0;
+	assertPackedInputCoverage(pages, group.inputs.length, `standalone texture in package "${pkg.getName()}"`);
 	for (let pageOffset = 0; pageOffset < pages.length; pageOffset += 1) {
 		const page = pages[pageOffset];
 		const baseFileName = resolveStandaloneAtlasOutputFileName(pkg, group.resource, group.branchName);
@@ -22169,6 +22337,12 @@ function packAtlasPages(inputs, options, forceSinglePage, sizeOverrides) {
 		preserveInputOrderOnTie: options.preserveInputOrderOnTie
 	}).pack(inputs.map((input, index) => inputToCompatRect(input, index))) ?? [];
 }
+function assertPackedInputCoverage(pages, inputCount, label) {
+	const packedIndexes = /* @__PURE__ */ new Set();
+	for (const page of pages) for (const outputRect of page.outputRects) packedIndexes.add(outputRect.index);
+	const hasEveryInput = Array.from({ length: inputCount }, (_, index) => packedIndexes.has(index)).every(Boolean);
+	if (packedIndexes.size !== inputCount || !hasEveryInput) throw new Error(`atlas: Could not pack every input for ${label}.`);
+}
 function attachSpritesToAtlas(doc, allResources, inputs, outputRects, atlasNode) {
 	for (const packedRect of outputRects) {
 		const input = inputs[packedRect.index];
@@ -22228,7 +22402,9 @@ async function writeAtlasPageImage(pkg, inputs, page, atlasFileName, encoder, op
 			} else if (input.rasterizedBuffer) imageBuffer = input.rasterizedBuffer;
 			else {
 				if (!isImageResource$1(input.resource)) {
-					logger.warn(`atlas: Non-image input "${input.id}" is missing inline buffer, skipping compositing.`);
+					const message = `atlas: Non-image input "${input.id}" is missing inline buffer.`;
+					if (options.strictOutput) throw new Error(message);
+					logger.warn(`${message} Skipping compositing.`);
 					continue;
 				}
 				imageBuffer = await encoder(_resolveImagePath(input.resource, pkg, options.basePath)).toBuffer();
@@ -22240,7 +22416,9 @@ async function writeAtlasPageImage(pkg, inputs, page, atlasFileName, encoder, op
 				top: packedRect.y
 			});
 		} catch {
-			logger.warn(`atlas: Could not read image "${input.id}" for compositing.`);
+			const message = `atlas: Could not read image "${input.id}" for compositing.`;
+			if (options.strictOutput) throw new Error(message);
+			logger.warn(message);
 		}
 	}
 	const outputFile = `${options.outputPath}/${atlasFileName}`;
@@ -22357,7 +22535,9 @@ async function emitDirectImageOutput(doc, pkg, input, encoder, options, logger,
 			}]).png().toFile(outputFile);
 		}
 	} catch {
-		logger.warn(`atlas: Could not write direct-output atlas "${atlasFileName}".`);
+		const message = `atlas: Could not write direct-output atlas "${atlasFileName}".`;
+		if (options.strictOutput) throw new Error(message);
+		logger.warn(message);
 	}
 }
 function getInputBranchName(input) {
@@ -22583,6 +22763,7 @@ async function _collectImage(resource, pkg, inputs, encoder, options, doTrim, lo
 				sourceHasAlpha = true;
 			}
 		} catch {
+			if (options.strictOutput) throw new Error(`atlas: Could not read image "${filePath}".`);
 			if (origW === 0 || origH === 0) {
 				logger.warn(`atlas: Could not read image "${filePath}", skipping.`);
 				return;
@@ -22621,7 +22802,11 @@ async function _collectImage(resource, pkg, inputs, encoder, options, doTrim, lo
 }
 /** Collect MovieClip frame textures from a .jta file into the inputs array. */
 async function _collectMovieClipFrames(doc, resource, pkg, inputs, encoder, options, logger) {
-	if (!options.basePath || !options.readFileRaw) return;
+	if (!options.basePath || !options.readFileRaw) {
+		if (options.strictOutput) throw new Error(`atlas: MovieClip "${resource.getId()}" requires basePath and readFileRaw for complete raster output.`);
+		return;
+	}
+	if (!encoder && options.strictOutput) throw new Error(`atlas: MovieClip "${resource.getId()}" requires an encoder for complete raster output.`);
 	const mcId = resource.getId();
 	const mcName = resource.getName() + ".jta";
 	const mcPath = resource.getPath() ?? "/";
@@ -22644,7 +22829,7 @@ async function _collectMovieClipFrames(doc, resource, pkg, inputs, encoder, opti
 				const exportFrameIndex = firstFrameIndexByTextureIndex.get(textureIndex);
 				if (exportFrameIndex === void 0) continue;
 				const itemId = `${mcId}_${exportFrameIndex}`;
-				const input = await _createMovieClipFrameInput(jta.frames[textureIndex], itemId, resource, encoder);
+				const input = await _createMovieClipFrameInput(jta.frames[textureIndex], itemId, resource, encoder, options.strictOutput);
 				if (!input) continue;
 				inputs.push(input);
 				spriteIdByTextureIndex.set(textureIndex, itemId);
@@ -22658,7 +22843,7 @@ async function _collectMovieClipFrames(doc, resource, pkg, inputs, encoder, opti
 			}
 		} else for (let frameIndex = 0; frameIndex < jta.frames.length; frameIndex += 1) {
 			const itemId = `${mcId}_${frameIndex}`;
-			const input = await _createMovieClipFrameInput(jta.frames[frameIndex], itemId, resource, encoder);
+			const input = await _createMovieClipFrameInput(jta.frames[frameIndex], itemId, resource, encoder, options.strictOutput);
 			if (!input) continue;
 			inputs.push(input);
 			const frame = doc.createMovieFrame(itemId);
@@ -22670,10 +22855,12 @@ async function _collectMovieClipFrames(doc, resource, pkg, inputs, encoder, opti
 			resource.setHeight(jta.meta?.height ?? 0);
 		}
 	} catch {
-		logger.warn(`atlas: Could not parse MovieClip "${filePath}", skipping frames.`);
+		const message = `atlas: Could not parse MovieClip "${filePath}".`;
+		if (options.strictOutput) throw new Error(message);
+		logger.warn(`${message} Skipping frames.`);
 	}
 }
-async function _createMovieClipFrameInput(buffer, itemId, resource, encoder) {
+async function _createMovieClipFrameInput(buffer, itemId, resource, encoder, strictOutput) {
 	if (!encoder || buffer.length === 0) return null;
 	try {
 		const meta = await encoder(buffer).metadata();
@@ -22693,6 +22880,7 @@ async function _createMovieClipFrameInput(buffer, itemId, resource, encoder) {
 			sourceKind: "movieclip-frame"
 		};
 	} catch {
+		if (strictOutput) throw new Error(`atlas: Could not decode MovieClip frame "${itemId}".`);
 		return null;
 	}
 }
@@ -23375,9 +23563,9 @@ function resolveProjectBasePath(basePath) {
 	const normalized = trimTrailingSlashes$2(basePath);
 	const assetsMatch = normalized.match(/^(.*)[/\\]assets(?:_[^/\\]+)?$/i);
 	if (assetsMatch?.[1]) return assetsMatch[1];
-	return dirname$2(normalized);
+	return dirname$1(normalized);
 }
-function dirname$2(filePath) {
+function dirname$1(filePath) {
 	return trimTrailingSlashes$2(filePath).match(/^(.*)[/\\][^/\\]+$/)?.[1] ?? "";
 }
 function trimTrailingSlashes$2(value) {
@@ -23522,10 +23710,16 @@ const TRANSPARENT_PNG_1X1 = Uint8Array.from([
 	96,
 	130
 ]);
+function assertSafeRestoreSegment(value, label) {
+	if (!value || value === "." || value === ".." || value.includes("\0") || /[\\/:]/u.test(value)) throw new Error(`restore: Invalid ${label} "${value}".`);
+}
 function normalizeVirtualPath(path) {
-	const normalized = (path ?? "").replace(/\\/g, "/").trim();
-	if (!normalized || normalized === "/") return "";
-	return normalized.replace(/^\/+/, "").replace(/\/+$/, "");
+	const raw = (path ?? "").trim();
+	if (!raw || raw === "/") return "";
+	if (raw.includes("\0") || raw.startsWith("\\") || raw.startsWith("//") || /^[a-z]:/iu.test(raw)) throw new Error(`restore: Invalid resource path "${raw}".`);
+	const segments = raw.replace(/\\/g, "/").split("/").filter(Boolean);
+	if (segments.some((segment) => segment === "." || segment === ".." || segment.includes(":"))) throw new Error(`restore: Invalid resource path "${raw}".`);
+	return segments.join("/");
 }
 function resourceFileName(resource) {
 	return resource.getFileName?.() || resource.getFile?.() || resource.getName?.() || "";
@@ -23709,44 +23903,40 @@ function normalizeComparablePath(value) {
 	const joined = segments.join("/");
 	return (drivePrefix ? `${drivePrefix}/${joined}`.replace(/\/$/, "") : hasRoot ? `/${joined}`.replace(/\/$/, "") : joined || ".").toLowerCase();
 }
-function dirname$1(filePath) {
-	return trimTrailingSlashes$1(filePath).match(/^(.*)[/\\][^/\\]+$/)?.[1] ?? "";
+function isPathWithin(root, candidate) {
+	const normalizedRoot = normalizeComparablePath(root);
+	return normalizeComparablePath(candidate).startsWith(`${normalizedRoot}/`);
 }
 function basename(filePath) {
 	return trimTrailingSlashes$1(filePath).match(/([^/\\]+)$/)?.[1] ?? "";
 }
-function resolveOutputProjectPath(output, fs) {
-	if (/\.fairy$/i.test(output)) return output;
-	const normalizedOutput = trimTrailingSlashes$1(output);
-	const projectName = basename(normalizedOutput) || "Restored";
-	return fs.join(normalizedOutput, `${projectName}.fairy`);
-}
-async function prepareRestoreOutputDir(inputDir, outputDir, outputProjectPath, fs, force, outputIsProjectFile) {
-	const [resolvedInputDir, resolvedOutputDir] = await Promise.all([Promise.resolve(fs.resolvePath(inputDir)), Promise.resolve(fs.resolvePath(outputDir))]);
-	if (normalizeComparablePath(resolvedInputDir) === normalizeComparablePath(resolvedOutputDir)) throw new Error("Restore output directory must be different from the published input directory.");
-	if (outputIsProjectFile) {
-		if (!await fs.exists(outputDir)) {
-			await fs.mkdir(outputDir);
-			return;
-		}
-		try {
-			await fs.readdir(outputDir);
-		} catch {
-			throw new Error(`Restore output path is not a directory: ${outputDir}`);
-		}
-		if (!await fs.exists(outputProjectPath)) return;
-		if (!force) throw new Error(`Restore output file already exists: ${outputProjectPath}. Use --force to overwrite it.`);
-		if (!fs.rm) throw new Error("Restore output file already exists and the provided fs does not support rm(...).");
-		await fs.rm(outputProjectPath, {
-			recursive: true,
-			force: true
-		});
-		return;
-	}
-	if (!await fs.exists(outputDir)) {
-		await fs.mkdir(outputDir);
-		return;
-	}
+function normalizeRestoreOutputDir(output) {
+	const normalized = trimTrailingSlashes$1(output);
+	const name = basename(normalized);
+	if (!normalized || /\.fairy$/i.test(normalized) || !name || name === "." || name === ".." || /^[a-z]:$/iu.test(name)) throw new Error("restore: Output must be a non-root project directory, not a .fairy file.");
+	return normalized;
+}
+function resolveOutputProjectPath(outputDir, fs) {
+	return fs.join(outputDir, `${basename(outputDir)}.fairy`);
+}
+async function resolvePathForContainment(filePath, fs) {
+	const missingSegments = [];
+	let existingPath = filePath;
+	while (!await fs.exists(existingPath)) {
+		const parentPath = fs.dirname(existingPath);
+		if (!parentPath || parentPath === existingPath) return Promise.resolve(fs.resolvePath(filePath));
+		missingSegments.unshift(basename(existingPath));
+		existingPath = parentPath;
+	}
+	const resolvedExistingPath = await Promise.resolve(fs.resolvePath(existingPath));
+	return missingSegments.reduce((resolvedPath, segment) => fs.join(resolvedPath, segment), resolvedExistingPath);
+}
+async function assertRestoreOutputDir(inputDir, outputDir, fs, force) {
+	const [resolvedInputDir, resolvedOutputDir] = await Promise.all([resolvePathForContainment(inputDir, fs), resolvePathForContainment(outputDir, fs)]);
+	const normalizedInputDir = normalizeComparablePath(resolvedInputDir);
+	const normalizedOutputDir = normalizeComparablePath(resolvedOutputDir);
+	if (normalizedInputDir === normalizedOutputDir || isPathWithin(normalizedInputDir, normalizedOutputDir) || isPathWithin(normalizedOutputDir, normalizedInputDir)) throw new Error("Restore output directory must be independent from the published input directory.");
+	if (!await fs.exists(outputDir)) return;
 	let entries;
 	try {
 		entries = await fs.readdir(outputDir);
@@ -23755,23 +23945,63 @@ async function prepareRestoreOutputDir(inputDir, outputDir, outputProjectPath, f
 	}
 	if (entries.length === 0) return;
 	if (!force) throw new Error(`Restore output directory is not empty: ${outputDir}. Use --force to overwrite it.`);
-	if (!fs.rm) throw new Error("Restore output directory is not empty and the provided fs does not support rm(...).");
-	await fs.rm(outputDir, {
-		recursive: true,
-		force: true
-	});
-	await fs.mkdir(outputDir);
+}
+async function createRestoreStagingDir(outputDir, fs) {
+	const parentDir = fs.dirname(outputDir) || ".";
+	await fs.mkdir(parentDir);
+	for (let attempt = 0; attempt < 8; attempt += 1) {
+		const stagingDir = fs.join(parentDir, `.${basename(outputDir)}.restore-${generateId()}`);
+		if (await fs.exists(stagingDir)) continue;
+		await fs.mkdir(stagingDir);
+		return stagingDir;
+	}
+	throw new Error(`restore: Could not allocate a staging directory beside ${outputDir}.`);
+}
+async function commitRestoreOutput(stagingDir, outputDir, fs) {
+	if (!await fs.exists(outputDir)) {
+		await fs.rename(stagingDir, outputDir);
+		return null;
+	}
+	const parentDir = fs.dirname(outputDir) || ".";
+	let backupDir = "";
+	for (let attempt = 0; attempt < 8; attempt += 1) {
+		const candidate = fs.join(parentDir, `.${basename(outputDir)}.restore-backup-${generateId()}`);
+		if (!await fs.exists(candidate)) {
+			backupDir = candidate;
+			break;
+		}
+	}
+	if (!backupDir) throw new Error(`restore: Could not allocate a backup directory beside ${outputDir}.`);
+	await fs.rename(outputDir, backupDir);
+	try {
+		await fs.rename(stagingDir, outputDir);
+	} catch (error) {
+		await fs.rename(backupDir, outputDir);
+		throw error;
+	}
+	try {
+		await fs.rm(backupDir, {
+			recursive: true,
+			force: true
+		});
+		return null;
+	} catch {
+		return `restore: Previous output retained at ${backupDir}; remove it after checking the restored project.`;
+	}
 }
 async function restore(options) {
 	const sourceDir = trimTrailingSlashes$1(options.inputDir);
-	const outputIsProjectFile = /\.fairy$/i.test(options.output);
-	const outputProjectPath = resolveOutputProjectPath(options.output, options.fs);
-	await prepareRestoreOutputDir(sourceDir, dirname$1(outputProjectPath) || ".", outputProjectPath, options.fs, options.force === true, outputIsProjectFile);
+	const outputDir = normalizeRestoreOutputDir(options.output);
+	const outputProjectPath = resolveOutputProjectPath(outputDir, options.fs);
+	await assertRestoreOutputDir(sourceDir, outputDir, options.fs, options.force === true);
 	const packageFilter = options.packages?.length ? new Set(options.packages) : null;
-	const candidateBinaryPaths = (await options.fs.readdir(sourceDir)).filter((name) => isPublishedBinaryFile(name)).filter((name) => !packageFilter || packageFilter.has(inferPackageName(name))).map((name) => options.fs.join(sourceDir, name)).sort((left, right) => left.localeCompare(right));
+	const binaryNames = (await options.fs.readdir(sourceDir)).filter((name) => isPublishedBinaryFile(name)).filter((name) => !packageFilter || packageFilter.has(inferPackageName(name)));
+	for (const binaryName of binaryNames) assertSafeRestoreSegment(binaryName, "published binary file name");
+	const candidateBinaryPaths = binaryNames.map((name) => options.fs.join(sourceDir, name)).sort((left, right) => left.localeCompare(right));
 	const binaryPaths = (await Promise.all(candidateBinaryPaths.map(async (filePath) => await options.fs.isFile(filePath) ? filePath : null))).filter((filePath) => !!filePath).sort((left, right) => left.localeCompare(right));
 	if (binaryPaths.length === 0) throw new Error(`No FairyGUI published binary files found in ${sourceDir}.`);
-	return new RestoreWorkflow(options.fs).restore({
+	const restorer = new RestoreWorkflow(options.fs);
+	const document = await restorer.prepare({
 		binaryPaths,
 		sourceDir,
 		outputProjectPath,
@@ -23779,18 +24009,45 @@ async function restore(options) {
 		cropImage: options.cropImage,
 		extractImage: options.extractImage
 	});
+	const stagingDir = await createRestoreStagingDir(outputDir, options.fs);
+	const stagingProjectPath = options.fs.join(stagingDir, basename(outputProjectPath));
+	const warnings = [];
+	try {
+		await restorer.write(document, {
+			binaryPaths,
+			sourceDir,
+			outputProjectPath: stagingProjectPath,
+			projectType: options.projectType,
+			cropImage: options.cropImage,
+			extractImage: options.extractImage
+		}, warnings);
+		const cleanupWarning = await commitRestoreOutput(stagingDir, outputDir, options.fs);
+		if (cleanupWarning) warnings.push(cleanupWarning);
+	} catch (error) {
+		await options.fs.rm(stagingDir, {
+			recursive: true,
+			force: true
+		}).catch(() => void 0);
+		throw error;
+	}
+	return {
+		document,
+		projectPath: outputProjectPath,
+		warnings
+	};
 }
 var RestoreWorkflow = class {
 	_fs;
 	constructor(fs) {
 		this._fs = fs;
 	}
-	async restore(options) {
-		const warnings = [];
+	async prepare(options) {
 		const doc = await new BinaryReader(this._fs).readMany(options.binaryPaths);
+		this._assertDocumentPaths(doc);
 		this._initializeProjectDefaults(doc, options.projectType);
 		this._initializeImageFileNames(doc);
 		this._initializeLooseResourceFileNames(doc);
+		this._assertDocumentPaths(doc);
 		await this._synthesizeLooseSkeletonResources(doc, options.sourceDir);
 		this._initializeRestoredResourceRelations(doc);
 		this._initializePublishedFontTextureIds(doc);
@@ -23799,13 +24056,27 @@ var RestoreWorkflow = class {
 		this._initializePublishedTextFontResources(doc);
 		this._initializeDisplayObjectFileNames(doc);
 		this._initializePublishedFontDefaults(doc);
+		this._assertDocumentPaths(doc);
+		return doc;
+	}
+	async write(doc, options, warnings) {
 		await new ProjectWriter(this._fs).write(doc, options.outputProjectPath);
 		await this._restoreAssets(doc, options, warnings);
-		return {
-			document: doc,
-			projectPath: options.outputProjectPath,
-			warnings
-		};
+	}
+	_assertDocumentPaths(doc) {
+		for (const pkg of doc.getRoot().listPackages()) {
+			assertSafeRestoreSegment(pkg.getName(), "package name");
+			assertSafeRestoreSegment(pkg.getPublishName() || pkg.getName(), "package publish name");
+			for (const resource of pkg.listResources()) {
+				normalizeVirtualPath(resource.getPath?.());
+				const branch = resource.getBranch?.() ?? "";
+				if (branch) assertSafeRestoreSegment(branch, "branch name");
+				const fileName = resourceFileName(resource);
+				if (fileName) assertSafeRestoreSegment(fileName, "resource file name");
+				const publishedFileName = resourcePublishedFileName(resource);
+				if (publishedFileName) assertSafeRestoreSegment(publishedFileName, "published resource file name");
+			}
+		}
 	}
 	_initializeProjectDefaults(doc, projectType) {
 		doc.getRoot().setProjectId(generateId()).setProjectType(projectType ?? ProjectType.Unity).setVersion("3.0").setSettings({
@@ -24239,27 +24510,40 @@ var RestoreWorkflow = class {
 	}
 	_sourceFileCandidates(pkg, fileName, outputFileName = fileName) {
 		const publishName = pkg.getPublishName() || pkg.getName();
-		return Array.from(new Set([
+		assertSafeRestoreSegment(publishName, "package publish name");
+		assertSafeRestoreSegment(fileName, "published source file name");
+		assertSafeRestoreSegment(outputFileName, "published source file name");
+		const candidates = Array.from(new Set([
 			`${publishName}_${fileName}`,
 			fileName,
 			`${publishName}_${outputFileName}`,
 			outputFileName
 		]));
+		for (const candidate of candidates) assertSafeRestoreSegment(candidate, "published source file name");
+		return candidates;
 	}
 	async _resolveLooseSourceFile(pkg, sourceDir, outputFileName) {
 		const candidates = outputFileName.endsWith(".atlas") ? this._sourceFileCandidates(pkg, `${outputFileName}.txt`, outputFileName) : outputFileName.endsWith(".skel") ? this._sourceFileCandidates(pkg, `${outputFileName}.bytes`, outputFileName) : this._sourceFileCandidates(pkg, outputFileName);
 		return this._resolveSourceFile(sourceDir, candidates);
 	}
 	async _resolveSourceFile(sourceDir, candidates) {
+		const resolvedSourceDir = await Promise.resolve(this._fs.resolvePath(sourceDir));
 		for (const candidate of candidates) {
+			assertSafeRestoreSegment(candidate, "published source file name");
 			const sourcePath = this._fs.join(sourceDir, candidate);
-			if (await this._fs.isFile(sourcePath)) return sourcePath;
+			if (!await this._fs.isFile(sourcePath)) continue;
+			const resolvedSourcePath = await Promise.resolve(this._fs.resolvePath(sourcePath));
+			if (!isPathWithin(resolvedSourceDir, resolvedSourcePath)) throw new Error(`restore: Published source file resolves outside the input directory: ${candidate}.`);
+			return resolvedSourcePath;
 		}
 		return null;
 	}
 	_resourceOutputPath(outputProjectPath, pkg, resource, fileName) {
 		const basePath = this._fs.dirname(outputProjectPath);
 		const branch = resource.getBranch?.() ?? "";
+		assertSafeRestoreSegment(pkg.getName(), "package name");
+		if (branch) assertSafeRestoreSegment(branch, "branch name");
+		assertSafeRestoreSegment(fileName, "resource file name");
 		const assetsDir = branch ? `assets_${branch}` : "assets";
 		const virtualPath = normalizeVirtualPath(resource.getPath?.());
 		const pkgDir = this._fs.join(basePath, assetsDir, pkg.getName());
@@ -24826,13 +25110,13 @@ function getPublishedSkeletonDependencyImageIds(pkg, publishedResourceIds) {
 	}
 	return imageIds;
 }
-async function exportPackageSounds(pkg, outputDir, basePath, fs, readFileRaw, logger) {
+async function exportPackageSounds(pkg, outputDir, basePath, fs, readFileRaw) {
 	const publishedResourceIds = getAnnotatedPublishedResourceIds(pkg);
 	if (publishedResourceIds.size === 0) return;
 	if (!basePath || !readFileRaw) {
 		if (pkg.listResources().some((resource) => {
 			return isSoundResource(resource) && publishedResourceIds.has(resource.getId());
-		})) logger.warn(`publish: Sound resources in package "${pkg.getName()}" were not exported because basePath/readFileRaw is unavailable.`);
+		})) throw new Error(`publish: Sound resources in package "${pkg.getName()}" require basePath and readFileRaw for output.`);
 		return;
 	}
 	for (const resource of pkg.listResources()) {
@@ -24845,18 +25129,18 @@ async function exportPackageSounds(pkg, outputDir, basePath, fs, readFileRaw, lo
 			const data = await readFileRaw(sourcePath);
 			await fs.writeFileRaw(targetPath, data);
 		} catch {
-			logger.warn(`publish: Could not export sound "${resource.getId()}" from package "${pkg.getName()}".`);
+			throw new Error(`publish: Could not export sound "${resource.getId()}" from package "${pkg.getName()}".`);
 		}
 	}
 }
-async function exportPackageExternalResources(pkg, outputDir, basePath, fs, readFileRaw, logger) {
+async function exportPackageExternalResources(pkg, outputDir, basePath, fs, readFileRaw) {
 	const exportedResourceIds = getAnnotatedExportedResourceIds(pkg);
 	const skeletonDependencyImageIds = getPublishedSkeletonDependencyImageIds(pkg, exportedResourceIds);
 	if (exportedResourceIds.size === 0) return;
 	if (!basePath || !readFileRaw) {
 		if (pkg.listResources().some((resource) => {
 			return (isMiscResource(resource) || isSkeletonResource(resource)) && exportedResourceIds.has(resource.getId()) || skeletonDependencyImageIds.has(resource.getId());
-		})) logger.warn(`publish: External resources in package "${pkg.getName()}" were not exported because basePath/readFileRaw is unavailable.`);
+		})) throw new Error(`publish: External resources in package "${pkg.getName()}" require basePath and readFileRaw for output.`);
 		return;
 	}
 	for (const resource of pkg.listResources()) {
@@ -24878,7 +25162,7 @@ async function exportPackageExternalResources(pkg, outputDir, basePath, fs, read
 			const data = await readFileRaw(sourcePath);
 			await fs.writeFileRaw(targetPath, data);
 		} catch {
-			logger.warn(`publish: Could not export external resource "${resource.getId()}" from package "${pkg.getName()}".`);
+			throw new Error(`publish: Could not export external resource "${resource.getId()}" from package "${pkg.getName()}".`);
 		}
 	}
 }
@@ -24894,18 +25178,17 @@ async function exportPackageExternalResources(pkg, outputDir, basePath, fs, read
 * `publishNode()` or `publishBrowser()` through their dedicated entries.
 *
 * ```ts
-* import sharp from 'sharp';
-* const io = new NodeIO();
-* const doc = await io.readProject('./project.fairy');
+* import { NodeIO } from '@openfairygui/core/node';
+* import { publishNode } from '@openfairygui/functions/node';
+* const doc = await new NodeIO().readProject('./project.fairy');
 *
-* await doc.transform(publish({
+* await publishNode({
+*   document: doc,
 *   output: './release/',
 *   compressed: true,
-*   encoder: sharp,
-*   basePath: './assets/',
+*   assetsPath: './assets/',
 *   fileExtension: 'bytes',
-*   fs: io.createFileSystem(),
-* }));
+* });
 * ```
 */
 function publish(options) {
@@ -24973,6 +25256,12 @@ function publish(options) {
 			}
 		});
 		const publishPackage = async (plan, writerFs, packageIndex) => {
+			if (options.fs && !plan.outputDir) throw new Error("publish: no output directory resolved. Provide --output, or configure global publish.path / package publishPath.");
+			if (options.fs) {
+				await options.fs.mkdir(plan.outputDir);
+				await exportPackageSounds(plan.pkg, plan.outputDir, options.basePath, options.fs, options.atlas?.readFileRaw ?? options.fs.readFileRaw);
+				await exportPackageExternalResources(plan.pkg, plan.outputDir, options.basePath, options.fs, options.atlas?.readFileRaw ?? options.fs.readFileRaw);
+			}
 			const atlasRuntimeOptions = resolvePublishAtlasRuntimeOptions(plan.fileExtension);
 			await atlas({
 				...plan.atlas,
@@ -24983,20 +25272,17 @@ function publish(options) {
 				outputPath: options.fs ? plan.outputDir : void 0,
 				mkdir: options.fs ? options.fs.mkdir : void 0,
 				readFileRaw: options.atlas?.readFileRaw ?? options.fs?.readFileRaw,
+				strictOutput: options.fs !== void 0,
 				packages: [plan.pkg.getName()],
 				...atlasRuntimeOptions
 			})(doc);
 			if (!options.fs) return;
-			if (!plan.outputDir) throw new Error("publish: no output directory resolved. Provide --output, or configure global publish.path / package publishPath.");
-			await options.fs.mkdir(plan.outputDir);
 			const filePath = options.fs.join(plan.outputDir, plan.fileName);
 			const bwOptions = {
 				compressed: plan.compressed,
 				packageIndex
 			};
 			await new BinaryWriter(writerFs).write(doc, filePath, bwOptions);
-			await exportPackageSounds(plan.pkg, plan.outputDir, options.basePath, options.fs, options.atlas?.readFileRaw ?? options.fs.readFileRaw, logger);
-			await exportPackageExternalResources(plan.pkg, plan.outputDir, options.basePath, options.fs, options.atlas?.readFileRaw ?? options.fs.readFileRaw, logger);
 			logger.info(`publish: Written ${plan.fileName}`);
 		};
 		const root = doc.getRoot();
@@ -25029,7 +25315,9 @@ function publish(options) {
 		}
 		const plans = allPackages.map((pkg) => resolvePackagePublishPlan(pkg, resolved, projectBasePath));
 		if (!options.fs) {
-			logger.info(`publish: No fs provided — layout computed for ${allPackages.length} package(s), skipping file output.`);
+			const outputPlan = plans.find((plan) => !!plan.outputDir);
+			if (outputPlan) throw new Error(`publish: Output for package "${outputPlan.pkg.getName()}" requires a filesystem. Omit output and publish paths to run a layout-only transform.`);
+			logger.info(`publish: Layout computed for ${allPackages.length} package(s); no output directory was requested.`);
 			const noopWriterFs = toBinaryWriterFileSystem(createNoopPublishFs());
 			for (const plan of plans) await publishPackage(plan, noopWriterFs, allDocPackages.indexOf(plan.pkg));
 			await runPublishPluginHook(plugins, "onPublishEnd", doc, options);
@@ -25216,6 +25504,9 @@ var NodeIO = class extends PlatformIO {
 					return false;
 				}
 			},
+			async unlink(filePath) {
+				await fs$1.unlink(filePath);
+			},
 			join(...paths) {
 				return path$1.join(...paths);
 			},
@@ -25358,8 +25649,8 @@ async function resolveNodeAssetsPath(document, assetsPath) {
 }
 async function loadSharpBackend() {
 	try {
-		const sharp = await importNative("sharp");
-		return sharp.default ?? sharp;
+		const loaded = await importNative("sharp");
+		return loaded.default ?? loaded;
 	} catch {
 		return;
 	}
@@ -25380,7 +25671,7 @@ async function publishNode(options) {
 	const { document, assetsPath: configuredAssetsPath, atlas, encoder: configuredEncoder, plugins: configuredPlugins, ...publishOptions } = 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) document.getLogger().warn("publish: Sharp is unavailable; atlas layout will be generated without PNG output.");
+	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,
@@ -25456,7 +25747,7 @@ function registerPublishCommand(program) {
 //#endregion
 //#region src/commands/restore.ts
 function registerRestoreCommand(program) {
-	program.command("restore").description("Restore a FairyGUI project from published binaries").argument("<release-dir>", "Published release directory").requiredOption("-o, --output <dir>", "Output project directory").option("-p, --packages <a,b,c>", "Only restore specific packages (comma-separated)").option("-f, --force", "Overwrite a non-empty output directory").option("-t, --project-type <name|id>", "Override restored project type; default is unity").action(async (releaseDir, options) => {
+	program.command("restore").description("Recover a project directory from trusted local published artifacts").argument("<release-dir>", "Published release directory").requiredOption("-o, --output <dir>", "Output project directory").option("-p, --packages <a,b,c>", "Only restore specific packages (comma-separated)").option("-f, --force", "Replace a non-empty output directory only after a complete staged restore").option("-t, --project-type <name|id>", "Override restored project type; default is unity").action(async (releaseDir, options) => {
 		const inputDir = path.resolve(releaseDir);
 		const outputDir = path.resolve(options.output);
 		const pkgFilter = options.packages ? options.packages.split(",").map((value) => value.trim()).filter(Boolean) : void 0;
@@ -25530,6 +25821,9 @@ function createNodeRestoreFs() {
 				force: options?.force ?? false
 			});
 		},
+		async rename(from, to) {
+			await fs.rename(from, to);
+		},
 		join(...paths) {
 			return path.join(...paths);
 		},

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openfairygui/cli",
-  "version": "0.2.0-alpha.13",
+  "version": "0.2.0-alpha.15",
   "description": "FairyGUI Headless Authoring SDK — command-line interface.",
   "author": "OpenFairyGUI Contributors",
   "license": "MIT",
@@ -33,13 +33,13 @@
     "restore"
   ],
   "devDependencies": {
-    "@openfairygui/core": "0.2.0-alpha.13",
-    "@openfairygui/functions": "0.2.0-alpha.13"
+    "@openfairygui/functions": "0.2.0-alpha.15",
+    "@openfairygui/core": "0.2.0-alpha.15"
   },
   "dependencies": {
     "commander": "^14.0.2",
     "jiti": "^2.7.0",
-    "@openfairygui/backend": "0.2.0-alpha.13"
+    "@openfairygui/backend": "0.2.0-alpha.15"
   },
   "optionalDependencies": {
     "sharp": ">=0.33.0"

package/src/commands/restore.ts

@@ -1,14 +1,14 @@
-import type { Command } from 'commander';
+import fs from 'node:fs/promises';
+import path from 'node:path';
 import {
-	restore,
 	type RestoreFileSystem,
 	type RestoreImageCropInput,
 	type RestoreImageCropper,
 	type RestoreImageExtractInput,
 	type RestoreImageExtractor,
+	restore,
 } from '@openfairygui/functions';
-import fs from 'node:fs/promises';
-import path from 'node:path';
+import type { Command } from 'commander';
 import { parseProjectType } from '../utils/project-type.js';
 
 type RestoreCommandOptions = {
@@ -26,11 +26,11 @@ interface RestoreImageProcessors {
 export function registerRestoreCommand(program: Command): void {
 	program
 		.command('restore')
-		.description('Restore a FairyGUI project from published binaries')
+		.description('Recover a project directory from trusted local published artifacts')
 		.argument('<release-dir>', 'Published release directory')
 		.requiredOption('-o, --output <dir>', 'Output project directory')
 		.option('-p, --packages <a,b,c>', 'Only restore specific packages (comma-separated)')
-		.option('-f, --force', 'Overwrite a non-empty output directory')
+		.option('-f, --force', 'Replace a non-empty output directory only after a complete staged restore')
 		.option('-t, --project-type <name|id>', 'Override restored project type; default is unity')
 		.action(async (releaseDir: string, options: RestoreCommandOptions) => {
 			const inputDir = path.resolve(releaseDir);
@@ -113,6 +113,9 @@ function createNodeRestoreFs(): RestoreFileSystem {
 		async rm(targetPath: string, options?: { recursive?: boolean; force?: boolean }): Promise<void> {
 			await fs.rm(targetPath, { recursive: options?.recursive ?? false, force: options?.force ?? false });
 		},
+		async rename(from: string, to: string): Promise<void> {
+			await fs.rename(from, to);
+		},
 		join(...paths: string[]): string {
 			return path.join(...paths);
 		},