@openfairygui/functions 0.2.0-alpha.2 → 0.2.0-alpha.21

package/src/restore.ts

@@ -3,10 +3,22 @@ import {
 	type Document,
 	type FileSystem,
 	generateId,
+	type Package,
 	ProjectType,
 	ProjectWriter,
-	type Package,
 } from '@openfairygui/core';
+import {
+	assertRestoreOutputDir,
+	basename,
+	commitRestoreOutput,
+	createRestoreStagingDir,
+	isPathWithin,
+	normalizeRestoreOutputDir,
+	resolveOutputProjectPath,
+	trimTrailingSlashes,
+} from './restore-internals/output-transaction.js';
+import { serializeFont, type RestorableFontGlyph } from './restore-internals/font.js';
+import { serializeMovieClip, type RestorableMovieFrame } from './restore-internals/movie-clip.js';
 
 export interface RestoreImageCropInput {
 	sourcePath: string;
@@ -45,7 +57,8 @@ export interface RestoreFileSystem extends Pick<FileSystem, 'readFile' | 'readFi
 	readdir(path: string): Promise<string[]>;
 	isFile(path: string): Promise<boolean>;
 	resolvePath(path: string): string | Promise<string>;
-	rm?: (path: string, options?: { recursive?: boolean; force?: boolean }) => Promise<void>;
+	rm(path: string, options?: { recursive?: boolean; force?: boolean }): Promise<void>;
+	rename(from: string, to: string): Promise<void>;
 }
 
 export interface RestoreOptions {
@@ -119,29 +132,6 @@ interface RestorableSprite {
 	getOriginalHeight(): number;
 }
 
-interface RestorableMovieFrame {
-	getRectX(): number;
-	getRectY(): number;
-	getRectWidth(): number;
-	getRectHeight(): number;
-	getAddDelay(): number;
-	getSpriteId(): string;
-}
-
-interface RestorableFontGlyph {
-	getAdvance(): number;
-	getChannel(): number;
-	getChar(): string;
-	getCharId(): number;
-	getHeight(): number;
-	getImg(): string;
-	getWidth(): number;
-	getX(): number;
-	getXOffset(): number;
-	getY(): number;
-	getYOffset(): number;
-}
-
 type RestorableFontResource = RestorableResource & {
 	listGlyphs(): RestorableFontGlyph[];
 	getBranch?(): string;
@@ -163,9 +153,6 @@ interface RestorableDisplayObject {
 	setFont?(font: string): unknown;
 }
 
-const JTA_FILE_MARK = 'yytou';
-const JTA_VERSION = 102;
-const JTA_DEFAULT_FPS = 24;
 const TRANSPARENT_PNG_1X1 = Uint8Array.from([
 	137, 80, 78, 71, 13, 10, 26, 10,
 	0, 0, 0, 13, 73, 72, 68, 82,
@@ -178,10 +165,23 @@ const TRANSPARENT_PNG_1X1 = Uint8Array.from([
 	66, 96, 130,
 ]);
 
+function assertSafeRestoreSegment(value: string, label: string): void {
+	if (!value || value === '.' || value === '..' || value.includes('\0') || /[\\/:]/u.test(value)) {
+		throw new Error(`restore: Invalid ${label} "${value}".`);
+	}
+}
+
 function normalizeVirtualPath(path: string | undefined): string {
-	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: RestorableResource): string {
@@ -338,59 +338,6 @@ function findImageResource(pkg: Package, itemId: string): RestorableResource | n
 	}) ?? null;
 }
 
-function fontGlyphCharId(glyph: RestorableFontGlyph): number {
-	const charId = glyph.getCharId();
-	if (charId > 0) return charId;
-	const char = glyph.getChar();
-	return char ? (char.codePointAt(0) ?? 0) : 0;
-}
-
-function scaledFrameDelay(milliseconds: number): number {
-	return milliseconds <= 0 ? 0 : Math.max(1, Math.round(milliseconds / (1000 / JTA_DEFAULT_FPS)));
-}
-
-function jtaSpeed(interval: number): number {
-	return interval <= 0 ? 1 : Math.max(1, Math.round(interval / (1000 / JTA_DEFAULT_FPS)));
-}
-
-function writeInt16(value: number): Uint8Array {
-	const data = new Uint8Array(2);
-	new DataView(data.buffer).setInt16(0, value);
-	return data;
-}
-
-function writeUint16(value: number): Uint8Array {
-	const data = new Uint8Array(2);
-	new DataView(data.buffer).setUint16(0, value);
-	return data;
-}
-
-function writeInt32(value: number): Uint8Array {
-	const data = new Uint8Array(4);
-	new DataView(data.buffer).setInt32(0, value);
-	return data;
-}
-
-function writeByte(value: number): Uint8Array {
-	return new Uint8Array([value & 0xff]);
-}
-
-function concatBytes(chunks: Uint8Array[]): Uint8Array {
-	const length = chunks.reduce((total, chunk) => total + chunk.byteLength, 0);
-	const data = new Uint8Array(length);
-	let offset = 0;
-	for (const chunk of chunks) {
-		data.set(chunk, offset);
-		offset += chunk.byteLength;
-	}
-	return data;
-}
-
-function encodeJtaUtf(value: string): Uint8Array {
-	const bytes = new TextEncoder().encode(value);
-	return concatBytes([writeUint16(bytes.byteLength), bytes]);
-}
-
 function isPublishedBinaryFile(fileName: string): boolean {
 	return /_fui\.bytes$/i.test(fileName) || /\.fui$/i.test(fileName) || /\.bin$/i.test(fileName);
 }
@@ -401,135 +348,18 @@ function inferPackageName(fileName: string): string {
 	return fileName.replace(/\.bin$/i, '');
 }
 
-function trimTrailingSlashes(value: string): string {
-	return value.replace(/[/\\]+$/, '');
-}
-
-function normalizeComparablePath(value: string): string {
-	const normalized = trimTrailingSlashes(value).replace(/\\/g, '/');
-	const driveMatch = normalized.match(/^([a-z]:)(?:\/(.*))?$/i);
-	const drivePrefix = driveMatch?.[1].toLowerCase() ?? '';
-	const remainder = driveMatch ? (driveMatch[2] ?? '') : normalized;
-	const hasRoot = driveMatch ? true : remainder.startsWith('/');
-	const rawSegments = remainder.split('/').filter((segment) => segment.length > 0);
-	const segments: string[] = [];
-
-	for (const segment of rawSegments) {
-		if (segment === '.') continue;
-		if (segment === '..') {
-			if (segments.length > 0 && segments[segments.length - 1] !== '..') {
-				segments.pop();
-			} else if (!hasRoot) {
-				segments.push('..');
-			}
-			continue;
-		}
-		segments.push(segment);
-	}
-
-	const joined = segments.join('/');
-	const comparable = drivePrefix
-		? `${drivePrefix}/${joined}`.replace(/\/$/, '')
-		: hasRoot
-			? `/${joined}`.replace(/\/$/, '')
-			: joined || '.';
-	// Restore prefers a conservative same-directory guard: false positives are safer than
-	// missing a Windows-style case-only path alias and deleting the source publish dir.
-	return comparable.toLowerCase();
-}
-
-function dirname(filePath: string): string {
-	const trimmed = trimTrailingSlashes(filePath);
-	const match = trimmed.match(/^(.*)[/\\][^/\\]+$/);
-	return match?.[1] ?? '';
-}
-
-function basename(filePath: string): string {
-	const trimmed = trimTrailingSlashes(filePath);
-	const match = trimmed.match(/([^/\\]+)$/);
-	return match?.[1] ?? '';
-}
-
-function resolveOutputProjectPath(output: string, fs: Pick<RestoreFileSystem, 'join'>): string {
-	if (/\.fairy$/i.test(output)) return output;
-	const normalizedOutput = trimTrailingSlashes(output);
-	const projectName = basename(normalizedOutput) || 'Restored';
-	return fs.join(normalizedOutput, `${projectName}.fairy`);
-}
-
-async function prepareRestoreOutputDir(
-	inputDir: string,
-	outputDir: string,
-	outputProjectPath: string,
-	fs: RestoreFileSystem,
-	force: boolean,
-	outputIsProjectFile: boolean,
-): Promise<void> {
-	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;
-	}
-
-	const exists = await fs.exists(outputDir);
-	if (!exists) {
-		await fs.mkdir(outputDir);
-		return;
-	}
-
-	let entries: string[];
-	try {
-		entries = await fs.readdir(outputDir);
-	} catch {
-		throw new Error(`Restore output path is not a directory: ${outputDir}`);
-	}
-
-	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);
-}
-
 export async function restore(options: RestoreOptions): Promise<RestoreResult> {
 	const sourceDir = trimTrailingSlashes(options.inputDir);
-	const outputIsProjectFile = /\.fairy$/i.test(options.output);
-	const outputProjectPath = resolveOutputProjectPath(options.output, options.fs);
-	const outputDir = dirname(outputProjectPath) || '.';
-	await prepareRestoreOutputDir(sourceDir, outputDir, 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))
+	const binaryNames = (await options.fs.readdir(sourceDir))
 		.filter((name) => isPublishedBinaryFile(name))
-		.filter((name) => !packageFilter || packageFilter.has(inferPackageName(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(
@@ -543,7 +373,7 @@ export async function restore(options: RestoreOptions): Promise<RestoreResult> {
 	}
 
 	const restorer = new RestoreWorkflow(options.fs);
-	return restorer.restore({
+	const document = await restorer.prepare({
 		binaryPaths,
 		sourceDir,
 		outputProjectPath,
@@ -551,6 +381,26 @@ export async function restore(options: RestoreOptions): Promise<RestoreResult> {
 		cropImage: options.cropImage,
 		extractImage: options.extractImage,
 	});
+	const stagingDir = await createRestoreStagingDir(outputDir, options.fs);
+	const stagingProjectPath = options.fs.join(stagingDir, basename(outputProjectPath));
+	const warnings: string[] = [];
+	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(() => undefined);
+		throw error;
+	}
+
+	return { document, projectPath: outputProjectPath, warnings };
 }
 
 class RestoreWorkflow {
@@ -560,13 +410,14 @@ class RestoreWorkflow {
 		this._fs = fs;
 	}
 
-	async restore(options: RestoreExecutionOptions): Promise<RestoreResult> {
-		const warnings: string[] = [];
+	async prepare(options: RestoreExecutionOptions): Promise<Document> {
 		const reader = new BinaryReader(this._fs);
 		const doc = await reader.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);
@@ -575,16 +426,30 @@ class RestoreWorkflow {
 		this._initializePublishedTextFontResources(doc);
 		this._initializeDisplayObjectFileNames(doc);
 		this._initializePublishedFontDefaults(doc);
+		this._assertDocumentPaths(doc);
+		return doc;
+	}
 
+	async write(doc: Document, options: RestoreExecutionOptions, warnings: string[]): Promise<void> {
 		const writer = new ProjectWriter(this._fs);
 		await writer.write(doc, options.outputProjectPath);
 		await this._restoreAssets(doc, options, warnings);
+	}
 
-		return {
-			document: doc,
-			projectPath: options.outputProjectPath,
-			warnings,
-		};
+	private _assertDocumentPaths(doc: Document): void {
+		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() as RestorableResource[]) {
+				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');
+			}
+		}
 	}
 
 	private _initializeProjectDefaults(doc: Document, projectType?: number): void {
@@ -757,9 +622,16 @@ class RestoreWorkflow {
 	): Promise<RestorableResource | null> {
 		const resources = pkg.listResources() as RestorableResource[];
 		const existing = this._findResourceByFile(resources, owner, 'ImageResource', fileName);
-		if (existing) return existing;
 		const sourcePath = await this._resolveLooseSourceFile(pkg, sourceDir, fileName);
-		if (!sourcePath) return null;
+		if (!sourcePath) return existing ?? null;
+		if (existing) {
+			existing.setExtras?.({
+				...(existing.getExtras?.() ?? {}),
+				_publishedFile: fileBaseName(sourcePath),
+				_restoreAsLooseImage: true,
+			});
+			return existing;
+		}
 		const resource = doc.createImageResource(stripExtension(fileName));
 		resource
 			.setId(generateId())
@@ -772,7 +644,7 @@ class RestoreWorkflow {
 			...(resource.getExtras?.() ?? {}),
 			_publishedFile: fileBaseName(sourcePath),
 			_suppressPackageSize: true,
-			_syntheticLooseImage: true,
+			_restoreAsLooseImage: true,
 		});
 		pkg.addResource(resource);
 		return resource as RestorableResource;
@@ -1022,8 +894,8 @@ class RestoreWorkflow {
 		warnings: string[],
 	): Promise<void> {
 		for (const resource of pkg.listResources() as RestorableResource[]) {
-			const syntheticLooseImage = resource.getExtras?.()?._syntheticLooseImage === true;
-			if (!['SoundResource', 'MiscResource', 'SpineResource', 'DragonBonesResource'].includes(resource.propertyType) && !syntheticLooseImage) {
+			const restoreAsLooseImage = resource.getExtras?.()?._restoreAsLooseImage === true;
+			if (!['SoundResource', 'MiscResource', 'SpineResource', 'DragonBonesResource'].includes(resource.propertyType) && !restoreAsLooseImage) {
 				continue;
 			}
 			const fileName = resourceFileName(resource);
@@ -1065,52 +937,7 @@ class RestoreWorkflow {
 
 		const outputPath = this._resourceOutputPath(outputProjectPath, pkg, resource, fileName);
 		await this._mkdirForFile(outputPath);
-		await this._fs.writeFile(outputPath, this._serializeFont(pkg, resource, glyphs));
-	}
-
-	private _serializeFont(pkg: Package, resource: RestorableResource, glyphs: RestorableFontGlyph[]): string {
-		const isTtf = resource.getTtf?.() === true;
-		const lines = isTtf
-			? this._serializeTtfFontHeader(pkg, resource, glyphs)
-			: [
-				'info creator=UIBuilder',
-				`common lineHeight=${resource.getLineHeight?.() ?? 0}`,
-			];
-
-		for (const glyph of glyphs) {
-			const charId = fontGlyphCharId(glyph);
-			if (isTtf) {
-				lines.push(
-					`char id=${charId} x=${glyph.getX()} y=${glyph.getY()} width=${glyph.getWidth()} height=${glyph.getHeight()} `
-					+ `xoffset=${glyph.getXOffset()} yoffset=${glyph.getYOffset()} xadvance=${glyph.getAdvance()} page=0 chnl=${glyph.getChannel()}`,
-				);
-			} else {
-				lines.push(
-					`char id=${charId} img=${glyph.getImg()} xoffset=${glyph.getXOffset()} yoffset=${glyph.getYOffset()} xadvance=${glyph.getAdvance()}`,
-				);
-			}
-		}
-
-		return `${lines.join('\n')}\n`;
-	}
-
-	private _serializeTtfFontHeader(pkg: Package, resource: RestorableResource, glyphs: RestorableFontGlyph[]): string[] {
-		const fileName = resourceFileName(resource);
-		const face = stripExtension(fileName) || resource.getName?.() || 'Font';
-		const lineHeight = resource.getLineHeight?.() ?? 0;
-		const fontSize = resource.getFontSize?.() ?? lineHeight;
-		const textureId = resource.getTextureId?.() ?? '';
-		const textureResource = textureId ? pkg.getResourceById(textureId) as RestorableResource | null : null;
-		const textureName = textureResource ? resourceFileName(textureResource) : `${face}_atlas.png`;
-		const scaleW = textureResource?.getWidth?.() ?? 256;
-		const scaleH = textureResource?.getHeight?.() ?? 256;
-		const base = Math.max(Math.min(fontSize, lineHeight) - 6, 0);
-		return [
-			`info face="${face}" size=${fontSize} bold=0 italic=0 charset="" unicode=1 stretchH=100 smooth=1 aa=1 padding=0,0,0,0 spacing=1,1 outline=0`,
-			`common lineHeight=${lineHeight} base=${base} scaleW=${scaleW} scaleH=${scaleH} pages=1 packed=0 alphaChnl=${resource.getTint?.() ? 1 : 0} redChnl=0 greenChnl=0 blueChnl=0`,
-			`page id=0 file="${textureName}"`,
-			`chars count=${glyphs.length}`,
-		];
+		await this._fs.writeFile(outputPath, serializeFont(pkg, resource, glyphs));
 	}
 
 	private async _writeMovieClipFile(
@@ -1157,7 +984,7 @@ class RestoreWorkflow {
 
 		const outputPath = this._resourceOutputPath(options.outputProjectPath, pkg, resource, fileName);
 		await this._mkdirForFile(outputPath);
-		await this._fs.writeFileRaw(outputPath, this._serializeMovieClip(resource, frames, textures));
+		await this._fs.writeFileRaw(outputPath, serializeMovieClip(resource, frames, textures));
 	}
 
 	private async _writeSyntheticFontGlyphImages(pkg: Package, outputProjectPath: string): Promise<void> {
@@ -1187,55 +1014,19 @@ class RestoreWorkflow {
 		return sprites;
 	}
 
-	private _serializeMovieClip(
-		resource: RestorableResource,
-		frames: RestorableMovieFrame[],
-		textures: Uint8Array[],
-	): Uint8Array {
-		const chunks: Uint8Array[] = [
-			encodeJtaUtf(JTA_FILE_MARK),
-			writeInt32(JTA_VERSION),
-			writeByte(0),
-			writeByte(0),
-			writeByte(0),
-			writeByte(0),
-			writeUint16(0),
-			writeUint16(0),
-			writeUint16(resource.getWidth?.() ?? 0),
-			writeUint16(resource.getHeight?.() ?? 0),
-			writeByte(jtaSpeed(resource.getInterval?.() ?? 0)),
-			writeByte(scaledFrameDelay(resource.getRepeatDelay?.() ?? 0)),
-			writeByte(resource.getSwing?.() ? 1 : 0),
-			writeInt16(frames.length),
-		];
-
-		for (const [index, frame] of frames.entries()) {
-			chunks.push(
-				writeInt16(scaledFrameDelay(frame.getAddDelay())),
-				writeInt16(frame.getRectX()),
-				writeInt16(frame.getRectY()),
-				writeInt16(frame.getRectWidth()),
-				writeInt16(frame.getRectHeight()),
-				writeInt16(textures[index]?.byteLength === 0 ? -1 : index),
-			);
-		}
-
-		chunks.push(writeInt16(textures.length));
-		for (const texture of textures) {
-			chunks.push(writeInt32(texture.byteLength), texture);
-		}
-
-		return concatBytes(chunks);
-	}
-
 	private _sourceFileCandidates(pkg: Package, fileName: string, outputFileName = fileName): string[] {
 		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;
 	}
 
 	private async _resolveLooseSourceFile(pkg: Package, sourceDir: string, outputFileName: string): Promise<string | null> {
@@ -1248,9 +1039,16 @@ class RestoreWorkflow {
 	}
 
 	private async _resolveSourceFile(sourceDir: string, candidates: string[]): Promise<string | null> {
+		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;
 	}
@@ -1263,6 +1061,9 @@ class RestoreWorkflow {
 	): string {
 		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());

package/src/shared-types.ts

@@ -1,4 +1,6 @@
-import type { FileSystem, ProjectSettings, PublishSettings } from '@openfairygui/core';
+import type { ProjectSettings, PublishSettings } from '@openfairygui/core';
+
+export type { PublishFileSystem } from './publish/contracts.js';
 
 export type ExtrasMap = Record<string, unknown>;
 
@@ -41,6 +43,7 @@ export interface PublishDependency {
 
 export interface PackagePublishArtifactsExtras extends ExtrasMap {
 	publishedResourceIds?: string[];
+	exportedResourceIds?: string[];
 	publishedIncludeBranches?: boolean;
 	publishedEffectiveResourceIds?: Record<string, string>;
 }
@@ -56,10 +59,3 @@ export interface HasOptionalSrc {
 export interface HasOptionalUrl {
 	getUrl?(): string | undefined;
 }
-
-export type PublishFileSystem = Pick<FileSystem, 'join' | 'mkdir' | 'writeFileRaw'> & {
-	deleteFile?: (path: string) => Promise<void>;
-	exists?: FileSystem['exists'];
-	readdir?: FileSystem['readdir'];
-	readFileRaw?: FileSystem['readFileRaw'];
-};

package/src/uam-transaction.ts

@@ -20,8 +20,10 @@ export interface ApplyUamTransactionAppError {
 	opIndex?: number;
 	opId?: string;
 	opKind?: UamTransactionOperation['kind'];
+	operationKind?: UamTransactionOperation['kind'];
 	selector?: Record<string, unknown>;
 	issues?: UamValidationIssue[] | UamTransactionSupportIssue[];
+	diagnostics: ApplyUamTransactionAppDiagnostic[];
 }
 
 export type ApplyUamTransactionAppResult =
@@ -41,6 +43,70 @@ function mapTransactionErrorStage(error: UamTransactionError): ApplyUamTransacti
 	}
 }
 
+export interface ApplyUamTransactionAppDiagnostic {
+	code: string;
+	message: string;
+	severity: 'error';
+	path?: string;
+	nodeKind?: string;
+	resourceKind?: string;
+	gearKind?: string;
+	field?: string;
+	operationKind?: UamTransactionOperation['kind'];
+	opIndex?: number;
+	opId?: string;
+}
+
+function compactDiagnostic(diagnostic: ApplyUamTransactionAppDiagnostic): ApplyUamTransactionAppDiagnostic {
+	return Object.fromEntries(Object.entries(diagnostic).filter(([, value]) => value !== undefined)) as ApplyUamTransactionAppDiagnostic;
+}
+
+function isTransactionSupportIssue(issue: UamValidationIssue | UamTransactionSupportIssue): issue is UamTransactionSupportIssue {
+	return 'code' in issue;
+}
+
+function mapTransactionDiagnostics(error: UamTransactionError): ApplyUamTransactionAppDiagnostic[] {
+	if (error.issues?.length) {
+		return error.issues.map((issue) => {
+			if (isTransactionSupportIssue(issue)) {
+				return compactDiagnostic({
+					code: issue.code,
+					message: issue.message,
+					severity: 'error' as const,
+					path: issue.path,
+					nodeKind: issue.nodeKind,
+					resourceKind: issue.resourceKind,
+					gearKind: issue.gearKind,
+					field: issue.field,
+					operationKind: issue.operationKind ?? error.opKind,
+					opIndex: error.opIndex,
+					opId: error.opId,
+				});
+			}
+			return compactDiagnostic({
+				code: error.code,
+				message: issue.message,
+				severity: 'error' as const,
+				path: issue.path,
+				operationKind: error.opKind,
+				opIndex: error.opIndex,
+				opId: error.opId,
+			});
+		});
+	}
+	return [
+		compactDiagnostic({
+			code: error.code,
+			message: error.message,
+			severity: 'error',
+			path: error.opIndex === undefined ? undefined : `operations[${error.opIndex}]`,
+			operationKind: error.opKind,
+			opIndex: error.opIndex,
+			opId: error.opId,
+		}),
+	];
+}
+
 export function applyUamTransactionApp(input: ApplyUamTransactionAppInput): ApplyUamTransactionAppResult {
 	try {
 		return {
@@ -58,8 +124,10 @@ export function applyUamTransactionApp(input: ApplyUamTransactionAppInput): Appl
 					opIndex: error.opIndex,
 					opId: error.opId,
 					opKind: error.opKind,
+					operationKind: error.opKind,
 					selector: error.selector,
 					issues: error.issues,
+					diagnostics: mapTransactionDiagnostics(error),
 				},
 			};
 		}