@openfairygui/cli 0.1.0 → 0.2.0-alpha.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@openfairygui/cli",
-	"version": "0.1.0",
+	"version": "0.2.0-alpha.0",
 	"description": "FairyGUI Headless Authoring SDK — command-line interface.",
 	"author": "OpenFairyGUI Contributors",
 	"license": "MIT",
@@ -39,6 +39,9 @@
 		"@openfairygui/core": "workspace:*",
 		"@openfairygui/functions": "workspace:*"
 	},
+	"dependencies": {
+		"@openfairygui/backend": "workspace:*"
+	},
 	"optionalDependencies": {
 		"sharp": ">=0.33.0"
 	}

package/src/cli.ts

@@ -1,16 +1,25 @@
+import { BackendRuntime } from '@openfairygui/backend';
 import {
 	NodeIO,
 	ProjectType,
+} from '@openfairygui/core';
+import {
+	inspect,
+	publish,
+	resolvePublishOptions,
+	restore,
+	type InspectReport,
+	type PublishOptions,
+	type RestoreFileSystem,
 	type RestoreImageCropInput,
 	type RestoreImageCropper,
 	type RestoreImageExtractInput,
 	type RestoreImageExtractor,
-} from '@openfairygui/core';
-import { inspect, publish, resolvePublishOptions, type InspectReport, type PublishOptions } from '@openfairygui/functions';
+} from '@openfairygui/functions';
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import { parseArgs } from 'node:util';
-
+
 const HELP = `
 ofgui — FairyGUI Headless Authoring CLI
 
@@ -21,6 +30,7 @@ Commands:
   inspect <project-dir>                          Show project contents report
   publish <project-dir> --output <dir> [options]  Publish project to binary outputs and configured generated code
   restore <release-dir> --output <dir> [options]  Restore a FairyGUI project from published binaries
+  backend-capabilities <project-dir>            Open a backend session, print runtime capabilities, then close it
 
 Publish options:
   --output, -o <dir>     Output directory (required)
@@ -36,69 +46,72 @@ Restore options:
   --project-type <name|id>  Override restored project type; default is unity
 
 Options:
-  --help, -h     Show this help
-  --version, -v  Show version
-
-Input can be a .fairy file or a project root directory (auto-discovers .fairy file).
-File extension and binary format are read from project settings.
-`;
-
-/** Resolve input to a .fairy file path. Accepts a directory or a .fairy file. */
-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()) {
-		// Scan for *.fairy in the directory
-		const entries = await fs.readdir(resolved);
-		const fairyFiles = entries.filter((e) => e.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}`);
-}
-
+  --help, -h     Show this help
+  --version, -v  Show version
+
+Input can be a .fairy file or a project root directory (auto-discovers .fairy file).
+File extension and binary format are read from project settings.
+`;
+
+/** Resolve input to a .fairy file path. Accepts a directory or a .fairy file. */
+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()) {
+		// Scan for *.fairy in the directory
+		const entries = await fs.readdir(resolved);
+		const fairyFiles = entries.filter((e) => e.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}`);
+}
+
 async function main(): Promise<void> {
-	const args = process.argv.slice(2);
-
-	if (args.length === 0 || args.includes('--help') || args.includes('-h')) {
-		console.log(HELP);
-		return;
-	}
-
-	if (args.includes('--version') || args.includes('-v')) {
-		console.log('0.1.0');
-		return;
-	}
-
-	const command = args[0];
-	const rest = args.slice(1);
-
-	switch (command) {
-		case 'inspect':
-			await cmdInspect(rest);
-			break;
+	const args = process.argv.slice(2);
+
+	if (args.length === 0 || args.includes('--help') || args.includes('-h')) {
+		console.log(HELP);
+		return;
+	}
+
+	if (args.includes('--version') || args.includes('-v')) {
+		console.log('0.1.0');
+		return;
+	}
+
+	const command = args[0];
+	const rest = args.slice(1);
+
+	switch (command) {
+		case 'inspect':
+			await cmdInspect(rest);
+			break;
 		case 'publish':
 			await cmdPublish(rest);
 			break;
 		case 'restore':
 			await cmdRestore(rest);
 			break;
+		case 'backend-capabilities':
+			await cmdBackendCapabilities(rest);
+			break;
 		default:
-			console.error(`Unknown command: ${command}\n`);
-			console.log(HELP);
-			process.exit(1);
-	}
+			console.error(`Unknown command: ${command}\n`);
+			console.log(HELP);
+			process.exit(1);
+	}
 }
 
 interface RestoreImageProcessors {
@@ -106,6 +119,63 @@ interface RestoreImageProcessors {
 	extractImage: RestoreImageExtractor;
 }
 
+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 {
@@ -140,7 +210,7 @@ async function createRestoreImageProcessors(): Promise<RestoreImageProcessors> {
 				|| input.offsetY + info.height > input.expectedHeight
 			) {
 				throw new Error(
-					`restore: Cropped image does not fit original canvas for ${input.outputPath}: `
+					`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}`,
 				);
@@ -190,41 +260,41 @@ async function createRestoreImageProcessors(): Promise<RestoreImageProcessors> {
 		},
 	};
 }
-
+
 async function cmdInspect(args: string[]): Promise<void> {
 	if (args.length === 0) {
 		console.error('Usage: ofgui inspect <project-dir>');
 		process.exit(1);
 	}
-
-	const fairyPath = await resolveFairyPath(args[0]);
-	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`);
+
+	const fairyPath = await resolveFairyPath(args[0]);
+	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`);
 	}
 }
 
@@ -282,8 +352,10 @@ async function cmdRestore(args: string[]): Promise<void> {
 	const { cropImage, extractImage } = await createRestoreImageProcessors();
 
 	console.log(`Restoring published FairyGUI project: ${releaseDir}`);
-	const io = new NodeIO();
-	const result = await io.restorePublishedProject(releaseDir, outputDir, {
+	const result = await restore({
+		inputDir: releaseDir,
+		output: outputDir,
+		fs: createNodeRestoreFs(),
 		packages: pkgFilter,
 		force: values.force,
 		projectType,
@@ -311,16 +383,16 @@ async function cmdPublish(args: string[]): Promise<void> {
 		},
 		allowPositionals: true,
 	});
-
+
 	if (positionals.length === 0 || !values.output) {
 		console.error('Usage: ofgui publish <project-dir> --output <dir> [--compressed] [--packages a,b,c] [--branch name]');
 		process.exit(1);
 	}
-
-	const fairyPath = await resolveFairyPath(positionals[0]);
-	const projectDir = path.dirname(fairyPath);
-	const outputDir = path.resolve(values.output);
-
+
+	const fairyPath = await resolveFairyPath(positionals[0]);
+	const projectDir = path.dirname(fairyPath);
+	const outputDir = path.resolve(values.output);
+
 	console.log(`Reading project: ${fairyPath}`);
 	const io = new NodeIO();
 	const doc = await io.readProject(fairyPath);
@@ -353,7 +425,7 @@ async function cmdPublish(args: string[]): Promise<void> {
 	try {
 		const sharp = await import('sharp');
 		encoder = sharp.default ?? sharp;
-		console.log('Sharp loaded — atlas PNGs will be generated.');
+		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');
@@ -367,7 +439,7 @@ async function cmdPublish(args: string[]): Promise<void> {
 		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 });
 		},
@@ -381,7 +453,7 @@ async function cmdPublish(args: string[]): Promise<void> {
 			return path.join(...paths);
 		},
 	};
-
+
 	await doc.transform(publish({
 		output: outputDir,
 		compressed: resolved.compressed,
@@ -393,11 +465,47 @@ async function cmdPublish(args: string[]): Promise<void> {
 		atlas: atlasConfig,
 		branch: values.branch,
 	}));
-
-	console.log(`\nDone! Output: ${outputDir}`);
-}
-
-main().catch((err) => {
-	console.error(err);
-	process.exit(1);
-});
+
+	console.log(`\nDone! Output: ${outputDir}`);
+}
+
+async function cmdBackendCapabilities(args: string[]): Promise<void> {
+	if (args.length === 0) {
+		console.error('Usage: ofgui backend-capabilities <project-dir>');
+		process.exit(1);
+	}
+
+	const runtime = new BackendRuntime();
+	const opened = await runtime.openSession({ projectPath: path.resolve(args[0]) });
+	if (!opened.ok) {
+		const failure = opened as Extract<typeof opened, { ok: false }>;
+		console.error(`backend-capabilities: ${failure.error.message}`);
+		process.exit(1);
+	}
+
+	const capabilities = runtime.getCapabilities();
+	if (!capabilities.ok) {
+		console.error('backend-capabilities: failed to read capabilities');
+		await runtime.closeSession({ sessionId: opened.data.sessionId });
+		process.exit(1);
+	}
+
+	console.log(`Session: ${opened.data.sessionId}`);
+	console.log(`Project: ${opened.data.canonicalProjectPath}`);
+	console.log(`Revision: ${opened.data.revision}`);
+	console.log(`Runtime owner: ${capabilities.data.runtimeOwner}`);
+	console.log(`Transaction owner: ${capabilities.data.transactionKernelOwner}`);
+	console.log(`App seam owner: ${capabilities.data.appSeamOwner}`);
+
+	const closed = await runtime.closeSession({ sessionId: opened.data.sessionId });
+	if (!closed.ok) {
+		const failure = closed as Extract<typeof closed, { ok: false }>;
+		console.error(`backend-capabilities: ${failure.error.message}`);
+		process.exit(1);
+	}
+}
+
+main().catch((err) => {
+	console.error(err);
+	process.exit(1);
+});