@openfairygui/cli 0.2.0-alpha.14 → 0.2.0-alpha.16

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

@@ -12582,16 +12582,26 @@ var ProjectWriter = class {
 			return attrs;
 		});
 		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);
+		const packageDescriptorPath = fs.join(pkgDir, "package.xml");
+		await fs.writeFile(packageDescriptorPath, this._renderPackageDescriptionXml(packageDescriptionAttrs, mainResources, publishAttrs));
+		currentSourceFilePaths.add(packageDescriptorPath);
+		for (const comp of mainResources.filter((resource) => resource.propertyType === "Component")) {
+			currentSourceFilePaths.add(fs.join(pkgDir, this._componentSourceRelativePath(comp)));
+			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);
+			const branchDescriptorPath = fs.join(branchPkgDir, "package_branch.xml");
+			await fs.writeFile(branchDescriptorPath, this._renderBranchDescriptionXml(branchResources));
+			currentSourceFilePaths.add(branchDescriptorPath);
+			for (const comp of branchResources.filter((resource) => resource.propertyType === "Component")) {
+				currentSourceFilePaths.add(fs.join(branchPkgDir, this._componentSourceRelativePath(comp)));
+				await this._writeComponent(comp, branchPkgDir);
+			}
 			await this._writeResourceSourceFiles(branchResources, branchPkgDir, currentSourceFilePaths);
 		}
 	}
@@ -21921,7 +21931,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();
@@ -22078,8 +22089,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])));
@@ -22168,6 +22180,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);
@@ -22265,7 +22278,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;
@@ -22291,7 +22304,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);
@@ -22334,6 +22347,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];
@@ -22393,7 +22412,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();
@@ -22405,7 +22426,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}`;
@@ -22522,7 +22545,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) {
@@ -22748,6 +22773,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;
@@ -22786,7 +22812,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() ?? "/";
@@ -22809,7 +22839,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);
@@ -22823,7 +22853,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);
@@ -22835,10 +22865,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();
@@ -22858,6 +22890,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;
 	}
 }
@@ -23540,9 +23573,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) {
@@ -23687,10 +23720,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?.() || "";
@@ -23874,44 +23913,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);
@@ -23920,23 +23955,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,
@@ -23944,18 +24019,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);
@@ -23964,13 +24066,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({
@@ -24404,27 +24520,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());
@@ -24991,13 +25120,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()) {
@@ -25010,18 +25139,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()) {
@@ -25043,7 +25172,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()}".`);
 		}
 	}
 }
@@ -25059,18 +25188,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) {
@@ -25138,6 +25266,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,
@@ -25148,20 +25282,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();
@@ -25194,7 +25325,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);
@@ -25548,7 +25681,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,
@@ -25624,7 +25757,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;
@@ -25698,6 +25831,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.14",
+  "version": "0.2.0-alpha.16",
   "description": "FairyGUI Headless Authoring SDK — command-line interface.",
   "author": "OpenFairyGUI Contributors",
   "license": "MIT",
@@ -33,13 +33,13 @@
     "restore"
   ],
   "devDependencies": {
-    "@openfairygui/functions": "0.2.0-alpha.14",
-    "@openfairygui/core": "0.2.0-alpha.14"
+    "@openfairygui/functions": "0.2.0-alpha.16",
+    "@openfairygui/core": "0.2.0-alpha.16"
   },
   "dependencies": {
     "commander": "^14.0.2",
     "jiti": "^2.7.0",
-    "@openfairygui/backend": "0.2.0-alpha.14"
+    "@openfairygui/backend": "0.2.0-alpha.16"
   },
   "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);
 		},