@openfairygui/cli 0.2.0-alpha.1 → 0.2.0-alpha.11

package/src/commands/inspect.ts

@@ -0,0 +1,44 @@
+import type { Command } from 'commander';
+import { inspect, type InspectReport } from '@openfairygui/functions';
+import { NodeIO } from '@openfairygui/core/node';
+import { resolveFairyPath } from '../utils/project-input.js';
+
+export function registerInspectCommand(program: Command): void {
+	program
+		.command('inspect')
+		.description('Show project contents report')
+		.argument('<project-dir>', 'Project root directory or .fairy file')
+		.action(async (projectDir: string) => {
+			const fairyPath = await resolveFairyPath(projectDir);
+			console.log(`Project: ${fairyPath}\n`);
+
+			const io = new NodeIO();
+			const doc = await io.readProject(fairyPath);
+			const report = inspect(doc);
+
+			printReport(report);
+		});
+}
+
+function printReport(report: InspectReport): void {
+	console.log(`ID: ${report.projectId}`);
+	console.log(`Type: ${report.projectType}, Version: ${report.version}`);
+	console.log(`\nPackages: ${report.totals.packages}`);
+	console.log(`  Images:       ${report.totals.images}`);
+	console.log(`  Sounds:       ${report.totals.sounds}`);
+	console.log(`  Fonts:        ${report.totals.fonts}`);
+	console.log(`  MovieClips:   ${report.totals.movieClips}`);
+	console.log(`  Components:   ${report.totals.components}`);
+	console.log(`  DisplayObjs:  ${report.totals.displayObjects}`);
+	console.log(`  Gears:        ${report.totals.gears}`);
+	console.log(`  Controllers:  ${report.totals.controllers}`);
+	console.log(`  Transitions:  ${report.totals.transitions}`);
+
+	console.log('\nPackage details:');
+	for (const pkg of report.packages) {
+		const res = pkg.resources;
+		console.log(
+			`  ${pkg.name} (${pkg.id}): ${res.images.count} img, ${res.sounds.count} snd, ${res.fonts.count} font, ${res.components.count} comp`,
+		);
+	}
+}

package/src/commands/publish.ts

@@ -0,0 +1,108 @@
+import type { Command } from 'commander';
+import { NodeIO } from '@openfairygui/core/node';
+import { publish, resolvePublishOptions, type PublishOptions } from '@openfairygui/functions';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { resolveFairyPath } from '../utils/project-input.js';
+import { parseProjectType } from '../utils/project-type.js';
+
+type PublishCommandOptions = {
+	output?: string;
+	compressed?: boolean;
+	packages?: string;
+	branch?: string;
+	projectType?: string;
+};
+
+export function registerPublishCommand(program: Command): void {
+	program
+		.command('publish')
+		.description('Publish project to binary outputs and configured generated code')
+		.argument('<project-dir>', 'Project root directory or .fairy file')
+		.option('-o, --output <dir>', 'Override project or package publish output directory')
+		.option('-c, --compressed', 'Compress binary data (overrides project setting)')
+		.option('-p, --packages <a,b,c>', 'Only publish specific packages (comma-separated)')
+		.option('-b, --branch <name>', 'Active branch used by "主干合并活跃分支"; omit for main branch')
+		.option('-t, --project-type <name|id>', 'Override project type (for example: unity, layabox, cocoscreator, 0, 4, 3)')
+		.action(async (projectDir: string, options: PublishCommandOptions) => {
+			const fairyPath = await resolveFairyPath(projectDir);
+			const projectRootDir = path.dirname(fairyPath);
+			const outputDir = options.output ? path.resolve(options.output) : undefined;
+
+			console.log(`Reading project: ${fairyPath}`);
+			const io = new NodeIO();
+			const doc = await io.readProject(fairyPath);
+			const projectType = parseProjectType(options.projectType);
+			if (projectType !== undefined) {
+				doc.getRoot().setProjectType(projectType);
+			}
+
+			const pkgFilter = options.packages?.split(',').map((value) => value.trim());
+			const resolved = resolvePublishOptions(doc, {
+				compressed: options.compressed,
+				packages: pkgFilter,
+			});
+
+			console.log(`Settings: ext=${resolved.fileExtension}, compressed=${resolved.compressed}`);
+			if (options.branch) {
+				console.log(`Active branch: ${options.branch}`);
+			}
+
+			const atlasConfig: NonNullable<PublishOptions['atlas']> = {
+				...resolved.atlas,
+				readFileRaw: async (filePath: string) => {
+					const buf = await fs.readFile(filePath);
+					return new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength);
+				},
+			};
+
+			let encoder: PublishOptions['encoder'];
+			try {
+				const sharp = await import('sharp');
+				encoder = sharp.default ?? sharp;
+				console.log('Sharp loaded — atlas PNGs will be generated.');
+			} catch {
+				console.log('Sharp not available — atlas PNGs will NOT be generated (layout only).');
+				console.log('  Install sharp to enable: pnpm add sharp');
+			}
+
+			const publishFs: NonNullable<PublishOptions['fs']> = {
+				async readFileRaw(filePath: string): Promise<Uint8Array> {
+					const buf = await fs.readFile(filePath);
+					return new Uint8Array(buf.buffer, buf.byteOffset, buf.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);
+				},
+			};
+
+			await doc.transform(
+				publish({
+					output: outputDir,
+					compressed: resolved.compressed,
+					fileExtension: resolved.fileExtension,
+					packages: resolved.packages,
+					fs: publishFs,
+					encoder,
+					basePath: path.join(projectRootDir, 'assets'),
+					atlas: atlasConfig,
+					branch: options.branch,
+				}),
+			);
+
+			console.log(`\nDone!${outputDir ? ` Output override: ${outputDir}` : ''}`);
+		});
+}

package/src/commands/restore.ts

@@ -0,0 +1,209 @@
+import type { Command } from 'commander';
+import {
+	restore,
+	type RestoreFileSystem,
+	type RestoreImageCropInput,
+	type RestoreImageCropper,
+	type RestoreImageExtractInput,
+	type RestoreImageExtractor,
+} from '@openfairygui/functions';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { parseProjectType } from '../utils/project-type.js';
+
+type RestoreCommandOptions = {
+	output: string;
+	packages?: string;
+	force?: boolean;
+	projectType?: string;
+};
+
+interface RestoreImageProcessors {
+	cropImage: RestoreImageCropper;
+	extractImage: RestoreImageExtractor;
+}
+
+export function registerRestoreCommand(program: Command): void {
+	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: string, options: RestoreCommandOptions) => {
+			const inputDir = path.resolve(releaseDir);
+			const outputDir = path.resolve(options.output);
+			const pkgFilter = options.packages
+				? options.packages
+						.split(',')
+						.map((value) => value.trim())
+						.filter(Boolean)
+				: undefined;
+			const projectType = parseProjectType(options.projectType);
+			const { cropImage, extractImage } = await createRestoreImageProcessors();
+
+			console.log(`Restoring published FairyGUI project: ${inputDir}`);
+			const result = await restore({
+				inputDir,
+				output: outputDir,
+				fs: createNodeRestoreFs(),
+				packages: pkgFilter,
+				force: options.force,
+				projectType,
+				cropImage,
+				extractImage,
+			});
+
+			const packages = result.document.getRoot().listPackages();
+			console.log(`\nDone! Output: ${result.projectPath}`);
+			console.log(`Packages: ${packages.map((pkg) => pkg.getName()).join(', ')}`);
+			for (const warning of result.warnings) {
+				console.warn(`Warning: ${warning}`);
+			}
+		});
+}
+
+function createNodeRestoreFs(): RestoreFileSystem {
+	return {
+		async readFile(filePath: string): Promise<string> {
+			return fs.readFile(filePath, 'utf-8');
+		},
+		async readFileRaw(filePath: string): Promise<Uint8Array> {
+			const buf = await fs.readFile(filePath);
+			return new Uint8Array(buf.buffer, buf.byteOffset, buf.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 });
+		},
+		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 mod = await import('sharp');
+		sharp = mod.default ?? mod;
+	} catch {
+		throw new Error('restore: sharp is required to crop atlas images. Install it with: pnpm add sharp');
+	}
+
+	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 (
+				input.expectedWidth > 0 &&
+				input.expectedHeight > 0 &&
+				(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;
+	}
+
+	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));
+		},
+	};
+}

package/src/utils/package-version.ts

@@ -0,0 +1,22 @@
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+
+function getInjectedPackageVersion(): string | null {
+	const version = (import.meta as ImportMeta & { env?: { PACKAGE_VERSION?: string } }).env?.PACKAGE_VERSION;
+	return typeof version === 'string' && version.length > 0 ? version : null;
+}
+
+export function readPackageVersion(): string {
+	const injectedVersion = getInjectedPackageVersion();
+	if (injectedVersion) return injectedVersion;
+	try {
+		const pkg = require('../../package.json') as { version?: unknown };
+		if (typeof pkg.version === 'string' && pkg.version.length > 0) {
+			return pkg.version;
+		}
+	} catch {
+		// Keep the CLI usable when executed from a bundled artifact missing package.json.
+	}
+	return '0.0.0-dev';
+}

package/src/utils/project-input.ts

@@ -0,0 +1,26 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+/** Resolve input to a .fairy file path. Accepts a directory or a .fairy file. */
+export async function resolveFairyPath(input: string): Promise<string> {
+	const resolved = path.resolve(input);
+	const stat = await fs.stat(resolved);
+
+	if (stat.isFile() && resolved.endsWith('.fairy')) {
+		return resolved;
+	}
+
+	if (stat.isDirectory()) {
+		const entries = await fs.readdir(resolved);
+		const fairyFiles = entries.filter((entry) => entry.endsWith('.fairy'));
+		if (fairyFiles.length === 1) {
+			return path.join(resolved, fairyFiles[0]);
+		}
+		if (fairyFiles.length > 1) {
+			throw new Error(`Multiple .fairy files found in ${resolved}: ${fairyFiles.join(', ')}. Please specify one.`);
+		}
+		throw new Error(`No .fairy file found in ${resolved}`);
+	}
+
+	throw new Error(`Input is not a .fairy file or directory: ${resolved}`);
+}

package/src/utils/project-type.ts

@@ -0,0 +1,31 @@
+import { ProjectType } from '@openfairygui/core';
+
+export function parseProjectType(value: string | undefined): number | undefined {
+	if (!value) return undefined;
+	const trimmed = value.trim();
+	if (trimmed === '') return undefined;
+	if (/^\d+$/u.test(trimmed)) return Number(trimmed);
+	const normalized = trimmed.toLowerCase();
+	const map: Record<string, number> = {
+		unity: ProjectType.Unity,
+		flash: ProjectType.Flash,
+		starling: ProjectType.Starling,
+		cocoscreator: ProjectType.CocosCreator,
+		cocos: ProjectType.CocosCreator,
+		layabox: ProjectType.LayaBox,
+		laya: ProjectType.LayaBox,
+		egret: ProjectType.Egret,
+		haxe: ProjectType.Haxe,
+		pixi: ProjectType.Pixi,
+		libgdx: ProjectType.LibGDX,
+		unreal: ProjectType.Unreal,
+		cryengine: ProjectType.CryEngine,
+		monogame: ProjectType.MonoGame,
+		vision: ProjectType.Vision,
+	};
+	const resolved = map[normalized];
+	if (resolved === undefined) {
+		throw new Error(`Unknown project type: ${value}. Use a numeric id or one of: ${Object.keys(map).join(', ')}`);
+	}
+	return resolved;
+}