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

package/src/adapters/node/plugins.ts

@@ -0,0 +1,82 @@
+import type { Document } from '@openfairygui/core';
+import {
+	formatPluginError,
+	type LoadedPlugin,
+	type Plugin,
+	type PluginManifest,
+	type PluginModule,
+} from '../../plugins/types.js';
+
+interface PluginPackageJson extends Partial<PluginManifest> {
+	name?: string;
+	main?: string;
+}
+
+// Keep Node builtins out of the neutral bundle resolver while still loading plugins in Node.
+const importNative = new Function('id', 'return import(id)') as <T>(id: string) => Promise<T>;
+
+export async function loadPlugins(doc: Document, pluginsDir: string): Promise<LoadedPlugin[]> {
+	if (!pluginsDir) return [];
+
+	const fs = await importNative<typeof import('node:fs/promises')>('node:fs/promises');
+	const path = await importNative<typeof import('node:path')>('node:path');
+	let entries: Array<{ name: string; isDirectory(): boolean }>;
+	try {
+		entries = await fs.readdir(pluginsDir, { withFileTypes: true });
+	} catch {
+		return [];
+	}
+
+	const plugins: LoadedPlugin[] = [];
+	for (const entry of entries) {
+		if (!entry.isDirectory()) continue;
+		const pluginDir = path.join(pluginsDir, entry.name);
+		try {
+			const manifest = await readPluginManifest(fs, path, pluginDir);
+			if (!manifest) continue;
+
+			const mainPath = resolvePluginMain(path, pluginDir, manifest);
+			const plugin = await loadPlugin(mainPath);
+			plugins.push({ name: manifest.name, plugin });
+		} catch (error) {
+			doc.getLogger().warn(`publish: Plugin "${entry.name}" was skipped: ${formatPluginError(error)}`);
+		}
+	}
+
+	return plugins;
+}
+
+async function readPluginManifest(
+	fs: typeof import('node:fs/promises'),
+	path: typeof import('node:path'),
+	pluginDir: string,
+): Promise<PluginPackageJson | null> {
+	const manifestPath = path.join(pluginDir, 'package.json');
+	const content = await fs.readFile(manifestPath, 'utf-8');
+	const manifest = JSON.parse(content) as PluginPackageJson;
+	if (!manifest.name) throw new Error(`Codegen plugin at ${pluginDir} is missing package.json name.`);
+	if (!manifest.main) throw new Error(`Codegen plugin "${manifest.name}" is missing package.json main.`);
+	return manifest;
+}
+
+function resolvePluginMain(path: typeof import('node:path'), pluginDir: string, manifest: PluginPackageJson): string {
+	const mainPath = path.resolve(pluginDir, manifest.main!);
+	const relative = path.relative(pluginDir, mainPath);
+	if (relative.startsWith('..') || path.isAbsolute(relative)) {
+		throw new Error(`Codegen plugin "${manifest.name}" main must resolve inside its plugin directory.`);
+	}
+	return mainPath;
+}
+
+async function loadPlugin(mainPath: string): Promise<Plugin> {
+	const { createJiti } = await importNative<typeof import('jiti')>('jiti');
+	const jiti = createJiti(import.meta.url);
+	const mod = await jiti.import<PluginModule>(mainPath);
+	const defaultExport = mod.default;
+	const plugin = isObject(defaultExport) ? defaultExport : mod;
+	return plugin as Plugin;
+}
+
+function isObject(value: unknown): value is Record<string, unknown> {
+	return value !== null && typeof value === 'object';
+}

package/src/adapters/node/publish.ts

@@ -0,0 +1,130 @@
+import type { Document } from '@openfairygui/core';
+import { resolveProjectBasePath } from '../../codegen.js';
+import type { LoadedPlugin } from '../../plugins/types.js';
+import type { AtlasRasterBackend, PublishFileSystem } from '../../publish/contracts.js';
+import { type PublishOptions, publish } from '../../publish.js';
+import { loadPlugins } from './plugins.js';
+
+const importNative = new Function('id', 'return import(id)') as <T>(id: string) => Promise<T>;
+
+interface NodePublishFileSystem extends PublishFileSystem {
+	readFileRaw(path: string): Promise<Uint8Array>;
+}
+
+export interface PublishNodeOptions extends Omit<PublishOptions, 'atlas' | 'basePath' | 'encoder' | 'fs' | 'plugins'> {
+	document: Document;
+	/**
+	 * Assets directory. Defaults to `<document project dir>/assets` when available.
+	 */
+	assetsPath?: string;
+	/**
+	 * Override the standard Sharp raster backend.
+	 */
+	encoder?: AtlasRasterBackend;
+	/**
+	 * Supply already-loaded hooks. Pass an empty array to skip project plugin discovery.
+	 */
+	plugins?: LoadedPlugin[];
+	atlas?: Omit<NonNullable<PublishOptions['atlas']>, 'readFileRaw'>;
+}
+
+async function createNodePublishFileSystem(): Promise<NodePublishFileSystem> {
+	const [fs, path] = await Promise.all([
+		importNative<typeof import('node:fs/promises')>('node:fs/promises'),
+		importNative<typeof import('node:path')>('node:path'),
+	]);
+
+	return {
+		async readFileRaw(filePath: string): Promise<Uint8Array> {
+			const data = await fs.readFile(filePath);
+			return new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
+		},
+		async writeFileRaw(filePath: string, data: Uint8Array): Promise<void> {
+			await fs.mkdir(path.dirname(filePath), { recursive: true });
+			await fs.writeFile(filePath, data);
+		},
+		async mkdir(dirPath: string): Promise<void> {
+			await fs.mkdir(dirPath, { recursive: true });
+		},
+		async readdir(dirPath: string): Promise<string[]> {
+			return fs.readdir(dirPath);
+		},
+		async deleteFile(filePath: string): Promise<void> {
+			await fs.rm(filePath, { force: true });
+		},
+		join(...paths: string[]): string {
+			return path.join(...paths);
+		},
+	};
+}
+
+async function resolveNodeAssetsPath(document: Document, assetsPath: string | undefined): Promise<string | undefined> {
+	if (assetsPath) return assetsPath;
+	const projectDir = document.getProjectDir?.() ?? '';
+	if (!projectDir) return undefined;
+	const path = await importNative<typeof import('node:path')>('node:path');
+	return path.join(projectDir, 'assets');
+}
+
+async function loadSharpBackend(): Promise<AtlasRasterBackend | undefined> {
+	try {
+		const loaded = await importNative<typeof import('sharp')>('sharp');
+		const sharp = loaded as unknown as { default?: AtlasRasterBackend };
+		return sharp.default ?? (loaded as unknown as AtlasRasterBackend);
+	} catch {
+		return undefined;
+	}
+}
+
+async function loadNodePublishPlugins(document: Document, assetsPath: string | undefined): Promise<LoadedPlugin[]> {
+	const projectDir = document.getProjectDir?.() || (assetsPath ? resolveProjectBasePath(assetsPath) : '');
+	if (!projectDir) return [];
+	const path = await importNative<typeof import('node:path')>('node:path');
+	return loadPlugins(document, path.join(projectDir, 'plugins'));
+}
+
+/**
+ * Publish a FairyGUI project through the standard Node host adapter.
+ *
+ * The adapter owns Node filesystem, Sharp, and project plugin discovery.
+ * For custom environments, use the lower-level `publish()` core with explicit
+ * capabilities instead.
+ */
+export async function publishNode(options: PublishNodeOptions): Promise<void> {
+	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 === undefined ? loadSharpBackend() : Promise.resolve(configuredEncoder),
+		configuredPlugins === undefined
+			? loadNodePublishPlugins(document, assetsPath)
+			: Promise.resolve(configuredPlugins),
+	]);
+
+	if (!encoder) {
+		throw new Error('publishNode: Sharp is required for a complete publish. Install sharp or provide an encoder.');
+	}
+
+	await document.transform(
+		publish({
+			...publishOptions,
+			basePath: assetsPath,
+			encoder,
+			atlas: {
+				...atlas,
+				readFileRaw: fileSystem.readFileRaw,
+			},
+			fs: fileSystem,
+			plugins,
+		}),
+	);
+}

package/src/adapters/node/restore.ts

@@ -0,0 +1,187 @@
+import type {
+	RestoreFileSystem,
+	RestoreImageCropInput,
+	RestoreImageCropper,
+	RestoreImageExtractInput,
+	RestoreImageExtractor,
+	RestoreOptions,
+	RestoreResult,
+} from '../../restore.js';
+import { restore } from '../../restore.js';
+
+const importNative = new Function('id', 'return import(id)') as <T>(id: string) => Promise<T>;
+
+interface RestoreImageProcessors {
+	cropImage: RestoreImageCropper;
+	extractImage: RestoreImageExtractor;
+}
+
+export interface RestoreNodeOptions extends Omit<RestoreOptions, 'fs' | 'cropImage' | 'extractImage'> {}
+
+async function createNodeRestoreFileSystem(): Promise<RestoreFileSystem> {
+	const [fs, path] = await Promise.all([
+		importNative<typeof import('node:fs/promises')>('node:fs/promises'),
+		importNative<typeof import('node:path')>('node:path'),
+	]);
+	return {
+		async readFile(filePath: string): Promise<string> {
+			return fs.readFile(filePath, 'utf-8');
+		},
+		async readFileRaw(filePath: string): Promise<Uint8Array> {
+			const buffer = await fs.readFile(filePath);
+			return new Uint8Array(buffer.buffer, buffer.byteOffset, buffer.byteLength);
+		},
+		async writeFile(filePath: string, content: string): Promise<void> {
+			await fs.mkdir(path.dirname(filePath), { recursive: true });
+			await fs.writeFile(filePath, content, 'utf-8');
+		},
+		async writeFileRaw(filePath: string, data: Uint8Array): Promise<void> {
+			await fs.mkdir(path.dirname(filePath), { recursive: true });
+			await fs.writeFile(filePath, data);
+		},
+		async mkdir(dirPath: string): Promise<void> {
+			await fs.mkdir(dirPath, { recursive: true });
+		},
+		async readdir(dirPath: string): Promise<string[]> {
+			return fs.readdir(dirPath);
+		},
+		async exists(filePath: string): Promise<boolean> {
+			try {
+				await fs.access(filePath);
+				return true;
+			} catch {
+				return false;
+			}
+		},
+		async isFile(filePath: string): Promise<boolean> {
+			try {
+				return (await fs.stat(filePath)).isFile();
+			} catch {
+				return false;
+			}
+		},
+		async resolvePath(filePath: string): Promise<string> {
+			try {
+				return await fs.realpath(filePath);
+			} catch {
+				return path.resolve(filePath);
+			}
+		},
+		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);
+		},
+		dirname(filePath: string): string {
+			return path.dirname(filePath);
+		},
+	};
+}
+
+async function createRestoreImageProcessors(): Promise<RestoreImageProcessors> {
+	let sharp: any;
+	try {
+		const loaded = await importNative<any>('sharp');
+		sharp = loaded.default ?? loaded;
+	} catch {
+		throw new Error('restoreNode: Sharp is required to crop atlas images. Install sharp before restoring.');
+	}
+
+	async function extractImage(input: RestoreImageExtractInput): Promise<Uint8Array> {
+		const targetPath = (input as RestoreImageCropInput).outputPath ?? input.sourcePath;
+		let image = sharp(input.sourcePath).extract({
+			left: input.left,
+			top: input.top,
+			width: input.width,
+			height: input.height,
+		});
+		if (input.rotated) image = image.rotate(90);
+		const { data, info } = await image.png().toBuffer({ resolveWithObject: true });
+		const needsOriginalCanvas =
+			input.expectedWidth > 0 &&
+			input.expectedHeight > 0 &&
+			(input.offsetX !== 0 ||
+				input.offsetY !== 0 ||
+				info.width !== input.expectedWidth ||
+				info.height !== input.expectedHeight);
+
+		if (needsOriginalCanvas) {
+			if (
+				input.offsetX < 0 ||
+				input.offsetY < 0 ||
+				input.offsetX + info.width > input.expectedWidth ||
+				input.offsetY + info.height > input.expectedHeight
+			) {
+				throw new Error(
+					`restore: Cropped image does not fit original canvas for ${targetPath}: ` +
+						`crop ${info.width}x${info.height} at ${input.offsetX},${input.offsetY}, ` +
+						`canvas ${input.expectedWidth}x${input.expectedHeight}`,
+				);
+			}
+			const composed = await sharp({
+				create: {
+					width: input.expectedWidth,
+					height: input.expectedHeight,
+					channels: 4,
+					background: { r: 0, g: 0, b: 0, alpha: 0 },
+				},
+			})
+				.composite([{ input: data, left: input.offsetX, top: input.offsetY }])
+				.png()
+				.toBuffer({ resolveWithObject: true });
+			if (
+				composed.info.width !== input.expectedWidth ||
+				composed.info.height !== input.expectedHeight
+			) {
+				throw new Error(
+					`restore: Cropped image size mismatch for ${targetPath}: ` +
+						`expected ${input.expectedWidth}x${input.expectedHeight}, ` +
+						`got ${composed.info.width}x${composed.info.height}`,
+				);
+			}
+			return composed.data;
+		}
+
+		if (
+			input.expectedWidth > 0 &&
+			input.expectedHeight > 0 &&
+			(info.width !== input.expectedWidth || info.height !== input.expectedHeight)
+		) {
+			throw new Error(
+				`restore: Cropped image size mismatch for ${targetPath}: ` +
+					`expected ${input.expectedWidth}x${input.expectedHeight}, got ${info.width}x${info.height}`,
+			);
+		}
+		return data;
+	}
+
+	const fs = await importNative<typeof import('node:fs/promises')>('node:fs/promises');
+	const path = await importNative<typeof import('node:path')>('node:path');
+	return {
+		extractImage,
+		cropImage: async (input: RestoreImageCropInput): Promise<void> => {
+			await fs.mkdir(path.dirname(input.outputPath), { recursive: true });
+			await fs.writeFile(input.outputPath, await extractImage(input));
+		},
+	};
+}
+
+/** Restore trusted local published artifacts through the standard Node host adapter. */
+export async function restoreNode(options: RestoreNodeOptions): Promise<RestoreResult> {
+	const [fs, imageProcessors] = await Promise.all([
+		createNodeRestoreFileSystem(),
+		createRestoreImageProcessors(),
+	]);
+	return restore({
+		...options,
+		fs,
+		...imageProcessors,
+	});
+}

package/src/adapters/web/publish.ts

@@ -0,0 +1,159 @@
+import { type Document, type ILogger, ProjectType } from '@openfairygui/core';
+import type { AtlasOptions } from '../../atlas.js';
+import { publish } from '../../publish.js';
+import type {
+	PublishFileSystem,
+	PublishOutputFileSystem,
+	PublishSourceFileSystem,
+} from '../../publish/contracts.js';
+import { assertBrowserImageSupport, createBrowserImageEncoder } from './raster.js';
+
+export type BrowserPublishProjectType = 'layabox';
+
+export type BrowserPublishAtlasOptions = Pick<
+	AtlasOptions,
+	| 'maxSize'
+	| 'fast'
+	| 'allowRotation'
+	| 'padding'
+	| 'powerOfTwo'
+	| 'square'
+	| 'multiPage'
+	| 'trimImage'
+	| 'extractAlpha'
+>;
+
+export type BrowserPublishSourceFileSystem = PublishSourceFileSystem;
+
+export type BrowserPublishOutputFileSystem = PublishOutputFileSystem;
+
+export interface BrowserPublishOptions {
+	document: Document;
+	sourceFileSystem: BrowserPublishSourceFileSystem;
+	outputFileSystem: BrowserPublishOutputFileSystem;
+	projectType: BrowserPublishProjectType;
+	output: string;
+	compressed?: boolean;
+	packages?: string[];
+	branch?: string;
+	atlas?: BrowserPublishAtlasOptions;
+}
+
+export interface BrowserPublishDiagnostic {
+	level: 'debug' | 'info' | 'warning' | 'error';
+	message: string;
+}
+
+export interface BrowserPublishedFile {
+	path: string;
+	size: number;
+}
+
+export interface BrowserPublishResult {
+	success: boolean;
+	files: BrowserPublishedFile[];
+	diagnostics: BrowserPublishDiagnostic[];
+}
+
+function createTrackingFileSystem(
+	fileSystem: BrowserPublishOutputFileSystem,
+	files: Map<string, number>,
+): PublishFileSystem {
+	const tracked: PublishFileSystem = {
+		join: (...paths) => fileSystem.join(...paths),
+		mkdir: (path) => fileSystem.mkdir(path),
+		writeFileRaw: async (path, data) => {
+			await fileSystem.writeFileRaw(path, data);
+			files.set(path, data.byteLength);
+		},
+	};
+	return tracked;
+}
+
+function createDiagnosticLogger(logger: ILogger, diagnostics: BrowserPublishDiagnostic[]): ILogger {
+	return {
+		debug(message) {
+			diagnostics.push({ level: 'debug', message });
+			logger.debug(message);
+		},
+		info(message) {
+			diagnostics.push({ level: 'info', message });
+			logger.info(message);
+		},
+		warn(message) {
+			diagnostics.push({ level: 'warning', message });
+			logger.warn(message);
+		},
+		error(message) {
+			diagnostics.push({ level: 'error', message });
+			logger.error(message);
+		},
+	};
+}
+
+function toResult(
+	success: boolean,
+	files: Map<string, number>,
+	diagnostics: BrowserPublishDiagnostic[],
+): BrowserPublishResult {
+	return {
+		success,
+		files: [...files].map(([path, size]) => ({ path, size })),
+		diagnostics,
+	};
+}
+
+/**
+ * Publish a loaded FairyGUI project to browser-provided storage.
+ *
+ * The adapter uses browser Canvas APIs for atlas composition, writes only through
+ * the supplied output filesystem, and intentionally skips Node publish plugins.
+ */
+export async function publishBrowser(options: BrowserPublishOptions): Promise<BrowserPublishResult> {
+	const files = new Map<string, number>();
+	const diagnostics: BrowserPublishDiagnostic[] = [];
+	const root = options.document.getRoot();
+	const previousProjectType = root.getProjectType();
+	const previousLogger = options.document.getLogger();
+	options.document.setLogger(createDiagnosticLogger(previousLogger, diagnostics));
+
+	try {
+		if (options.projectType !== 'layabox') {
+			throw new Error(`publishBrowser: unsupported project type "${String(options.projectType)}".`);
+		}
+		assertBrowserImageSupport();
+		root.setProjectType(ProjectType.LayaBox);
+		const outputFileSystem = createTrackingFileSystem(options.outputFileSystem, files);
+		const sourceAssetsPath = options.sourceFileSystem.join(options.document.getProjectDir(), 'assets');
+
+		await options.document.transform(
+			publish({
+				output: options.output,
+				compressed: options.compressed,
+				fileExtension: 'fui',
+				packages: options.packages,
+				branch: options.branch,
+				basePath: sourceAssetsPath,
+				encoder: createBrowserImageEncoder(options.sourceFileSystem, outputFileSystem),
+				atlas: {
+					...options.atlas,
+					readFileRaw: (path) => options.sourceFileSystem.readFileRaw(path),
+				},
+				fs: outputFileSystem,
+				plugins: [],
+				codeGeneration: false,
+			}),
+		);
+
+		return toResult(true, files, diagnostics);
+	} catch (error) {
+		diagnostics.push({
+			level: 'error',
+			message: error instanceof Error ? error.message : String(error),
+		});
+		return toResult(false, files, diagnostics);
+	} finally {
+		root.setProjectType(previousProjectType);
+		options.document.setLogger(previousLogger);
+	}
+}