@openfairygui/cli 0.2.0-alpha.29 → 0.2.0-alpha.30

package/dist/cli.mjs

@@ -1314,6 +1314,7 @@ var Package = class extends ExtensibleProperty {
 			publishPackageCount: 0,
 			genCode: false,
 			codePath: "",
+			resourceFolders: [],
 			resources: new RefSet(),
 			atlases: new RefSet(),
 			dependencies: new RefSet()
@@ -1373,6 +1374,12 @@ var Package = class extends ExtensibleProperty {
 	setCodePath(path) {
 		return this.set("codePath", path);
 	}
+	listResourceFolders() {
+		return this.get("resourceFolders").map((folder) => ({ ...folder }));
+	}
+	setResourceFolders(folders) {
+		return this.set("resourceFolders", folders.map((folder) => ({ ...folder })));
+	}
 	addResource(resource) {
 		return this.addRef("resources", resource);
 	}
@@ -9837,6 +9844,20 @@ var Document = class Document {
 	}
 };
 //#endregion
+//#region ../core/src/utils/resource-folder.ts
+function normalizeResourceFolderPath(value) {
+	const segments = value.replace(/\\/g, "/").split("/").filter(Boolean);
+	return segments.length > 0 ? `/${segments.join("/")}/` : "/";
+}
+function resourceFolderParentPath(value) {
+	const segments = normalizeResourceFolderPath(value).split("/").filter(Boolean);
+	segments.pop();
+	return segments.length > 0 ? `/${segments.join("/")}/` : "/";
+}
+function resourceFolderName(value) {
+	return normalizeResourceFolderPath(value).split("/").filter(Boolean).pop() ?? "";
+}
+//#endregion
 //#region ../core/src/io/project-xml-protocol.ts
 const mergeAttrs = (...parts) => Object.assign({}, ...parts);
 const mergeChildren = (...parts) => Object.assign({}, ...parts);
@@ -9876,6 +9897,13 @@ const PACKAGE_RESOURCE_BASE_ATTRS = {
 	exported: { canonical: "exported" },
 	favorite: { canonical: "favorite" }
 };
+const PACKAGE_RESOURCE_FOLDER_ATTRS = {
+	id: PACKAGE_RESOURCE_BASE_ATTRS.id,
+	name: PACKAGE_RESOURCE_BASE_ATTRS.name,
+	path: PACKAGE_RESOURCE_BASE_ATTRS.path,
+	favorite: PACKAGE_RESOURCE_BASE_ATTRS.favorite,
+	atlas: { canonical: "atlas" }
+};
 const PACKAGE_IMAGE_RESOURCE_ATTRS = {
 	atlas: { canonical: "atlas" },
 	scale: { canonical: "scale" },
@@ -10264,6 +10292,7 @@ const BRANCH_DESCRIPTION_NODE = defineNode(BRANCH_DESCRIPTION_ATTRS);
 const PACKAGE_PUBLISH_ATLAS_NODE = defineNode(PACKAGE_PUBLISH_ATLAS_ATTRS);
 const PACKAGE_PUBLISH_NODE = defineNode(PACKAGE_PUBLISH_ATTRS, { atlas: PACKAGE_PUBLISH_ATLAS_NODE });
 const PACKAGE_RESOURCE_NODE = defineNode(PACKAGE_RESOURCE_BASE_ATTRS);
+const PACKAGE_RESOURCE_FOLDER_NODE = defineNode(PACKAGE_RESOURCE_FOLDER_ATTRS);
 const PACKAGE_IMAGE_RESOURCE_NODE = defineNode(PACKAGE_IMAGE_RESOURCE_ATTRS);
 const PACKAGE_FONT_RESOURCE_NODE = defineNode(PACKAGE_FONT_RESOURCE_ATTRS);
 const PACKAGE_MOVIE_CLIP_RESOURCE_NODE = defineNode(PACKAGE_MOVIE_CLIP_RESOURCE_ATTRS);
@@ -10356,6 +10385,7 @@ const PROJECT_XML_PROTOCOL = {
 	packagePublish: PACKAGE_PUBLISH_NODE,
 	packagePublishAtlas: PACKAGE_PUBLISH_ATLAS_NODE,
 	packageResource: PACKAGE_RESOURCE_NODE,
+	packageResourceFolder: PACKAGE_RESOURCE_FOLDER_NODE,
 	packageImageResource: PACKAGE_IMAGE_RESOURCE_NODE,
 	packageFontResource: PACKAGE_FONT_RESOURCE_NODE,
 	packageMovieClipResource: PACKAGE_MOVIE_CLIP_RESOURCE_NODE,
@@ -12294,9 +12324,10 @@ function readImageSize(data) {
 	return readPngSize(data) ?? readJpegSize(data);
 }
 function getOrderedPackageResourceItems(xmlContent) {
-	const packageEntry = parseXMLPreserveOrder(xmlContent).find((entry) => "packageDescription" in entry);
-	if (!packageEntry) return [];
-	const resourcesEntry = (Array.isArray(packageEntry.packageDescription) ? packageEntry.packageDescription : []).find((entry) => "resources" in entry);
+	const descriptionEntry = parseXMLPreserveOrder(xmlContent).find((entry) => "packageDescription" in entry || "branchDescription" in entry);
+	if (!descriptionEntry) return [];
+	const description = "packageDescription" in descriptionEntry ? descriptionEntry.packageDescription : descriptionEntry.branchDescription;
+	const resourcesEntry = (Array.isArray(description) ? description : []).find((entry) => "resources" in entry);
 	if (!resourcesEntry) return [];
 	return (Array.isArray(resourcesEntry.resources) ? resourcesEntry.resources : []).flatMap((entry) => {
 		const tagName = Object.keys(entry).find((key) => key !== ":@" && key !== "#text");
@@ -12466,13 +12497,16 @@ var ProjectReader = class {
 			pkg.setCodePath(readXmlAttr(publish, PROJECT_XML_PROTOCOL.packagePublish.attrs.codePath) || "");
 		}
 		if (pkg.getId()) ctx.packageMap.set(pkg.getId(), pkg);
+		const packageDir = branchName ? fs.join(ctx.basePath, `assets_${branchName}`, dirName) : fs.join(ctx.basePath, "assets", dirName);
 		const resources = desc.resources;
+		const orderedResources = getOrderedPackageResourceItems(content);
+		const folderEntries = orderedResources.length > 0 ? orderedResources.filter((entry) => entry.tagName === "folder").map((entry) => entry.attrs) : ensureArray(resources?.folder).map((entry) => getXmlNode(entry)).filter((entry) => !!entry);
+		await this._readPackageFolders(pkg, packageDir, branchName, folderEntries);
 		if (!resources) return;
-		const packageDir = branchName ? fs.join(ctx.basePath, `assets_${branchName}`, dirName) : fs.join(ctx.basePath, "assets", dirName);
 		const createdResources = [];
-		const orderedResources = getOrderedPackageResourceItems(content);
 		if (orderedResources.length > 0) {
 			for (const { tagName, attrs } of orderedResources) {
+				if (tagName === "folder") continue;
 				const resource = this._createResourceFromXML(ctx, pkg, tagName, attrs, packageDir, branchName);
 				if (resource) createdResources.push(resource);
 			}
@@ -12503,6 +12537,40 @@ var ProjectReader = class {
 		await this._hydratePackageImageSizes(createdResources, packageDir);
 		if (options.hydrateResourceBytes) await this._hydratePackageResourceBytes(ctx.document, createdResources, packageDir);
 	}
+	async _readPackageFolders(pkg, packageDir, branch, metadataEntries) {
+		const metadata = new Map(metadataEntries.map((attrs) => {
+			return [normalizeResourceFolderPath(`${readXmlAttr(attrs, PROJECT_XML_PROTOCOL.packageResourceFolder.attrs.path) ?? "/"}/${readXmlAttr(attrs, PROJECT_XML_PROTOCOL.packageResourceFolder.attrs.name) ?? ""}`), attrs];
+		}));
+		const folders = pkg.listResourceFolders();
+		const visit = async (directory, parentPath, entries) => {
+			let names = entries;
+			if (!names) try {
+				names = await this._fs.readdir(directory);
+			} catch {
+				return;
+			}
+			for (const name of [...names].sort((left, right) => left.localeCompare(right))) {
+				const childDirectory = this._fs.join(directory, name);
+				let childEntries;
+				try {
+					childEntries = await this._fs.readdir(childDirectory);
+				} catch {
+					continue;
+				}
+				const path = normalizeResourceFolderPath(`${parentPath}/${name}`);
+				const attrs = metadata.get(path);
+				folders.push({
+					branch,
+					path,
+					favorite: parseBool(readXmlAttr(attrs ?? {}, PROJECT_XML_PROTOCOL.packageResourceFolder.attrs.favorite)),
+					atlas: readXmlAttr(attrs ?? {}, PROJECT_XML_PROTOCOL.packageResourceFolder.attrs.atlas) ?? ""
+				});
+				await visit(childDirectory, path, childEntries);
+			}
+		};
+		await visit(packageDir, "/");
+		pkg.setResourceFolders(folders);
+	}
 	async _hydratePackageImageSizes(resources, packageDir) {
 		const fs = this._fs;
 		for (const resource of resources) {
@@ -14099,6 +14167,7 @@ var ProjectWriter = class {
 		const root = doc.getRoot();
 		const basePath = fs.dirname(projectPath);
 		const currentSourceFilePaths = /* @__PURE__ */ new Set();
+		const currentResourceFolderPaths = /* @__PURE__ */ new Set();
 		const staleSourceFilePaths = new Set((options.staleSourceFiles ?? []).map((source) => this._projectSourceFilePath(basePath, source)));
 		for (const pkg of root.listPackages()) this._assertPackageOutputTargets(pkg);
 		const fairyXml = `<?xml version="1.0" encoding="utf-8"?>\n<projectDescription id="${root.getProjectId()}" type="${this._projectTypeName(root.getProjectType())}" version="${root.getVersion() || "3.0"}"/>\n`;
@@ -14113,23 +14182,31 @@ var ProjectWriter = class {
 		})) if (settings[key]) await fs.writeFile(fs.join(settingsPath, fileName), JSON.stringify(settings[key], null, "	"));
 		const assetsPath = fs.join(basePath, "assets");
 		await fs.mkdir(assetsPath);
-		for (const pkg of root.listPackages()) await this._writePackage(doc, pkg, assetsPath, currentSourceFilePaths);
+		for (const pkg of root.listPackages()) await this._writePackage(doc, pkg, assetsPath, currentSourceFilePaths, currentResourceFolderPaths);
 		await this._removeStaleSourceFiles(currentSourceFilePaths, staleSourceFilePaths);
+		await this._removeStaleResourceFolders(currentResourceFolderPaths, new Set((options.staleResourceFolders ?? []).map((folder) => this._projectResourceFolderPath(basePath, folder))));
 	}
-	async _writePackage(_doc, pkg, assetsPath, currentSourceFilePaths) {
+	async _writePackage(_doc, pkg, assetsPath, currentSourceFilePaths, currentResourceFolderPaths) {
 		const fs = this._fs;
 		this._assertSafePathSegment(pkg.getName(), "package name");
 		const pkgDir = fs.join(assetsPath, pkg.getName());
 		await fs.mkdir(pkgDir);
 		const basePath = fs.dirname(assetsPath);
 		const resourcesByBranch = /* @__PURE__ */ new Map();
+		const foldersByBranch = /* @__PURE__ */ new Map();
 		for (const res of pkg.listResources()) {
 			const branchName = res.getBranch?.() ?? "";
 			const bucket = resourcesByBranch.get(branchName) ?? [];
 			bucket.push(res);
 			resourcesByBranch.set(branchName, bucket);
 		}
+		for (const folder of pkg.listResourceFolders()) {
+			const bucket = foldersByBranch.get(folder.branch) ?? [];
+			bucket.push(folder);
+			foldersByBranch.set(folder.branch, bucket);
+		}
 		const mainResources = resourcesByBranch.get("") ?? [];
+		const mainFolders = foldersByBranch.get("") ?? [];
 		const publishName = pkg.getPublishName() || pkg.getName();
 		const publishPath = pkg.getPublishPath();
 		const publishBranchPath = pkg.getPublishBranchPath();
@@ -14138,7 +14215,7 @@ var ProjectWriter = class {
 		const codePath = pkg.getCodePath();
 		const packageDescriptionAttrs = {};
 		writeXmlAttr(packageDescriptionAttrs, PROJECT_XML_PROTOCOL.packageDescription.attrs.id, pkg.getId());
-		if (pkg.listResources().some((resource) => resource.getFavorite?.())) writeXmlAttr(packageDescriptionAttrs, PROJECT_XML_PROTOCOL.packageDescription.attrs.hasFavorites, "true");
+		if (pkg.listResources().some((resource) => resource.getFavorite?.()) || pkg.listResourceFolders().some((folder) => folder.favorite)) writeXmlAttr(packageDescriptionAttrs, PROJECT_XML_PROTOCOL.packageDescription.attrs.hasFavorites, "true");
 		const compressPNG = pkg.getCompressPNG();
 		if (compressPNG !== null) writeXmlAttr(packageDescriptionAttrs, PROJECT_XML_PROTOCOL.packageDescription.attrs.compressPNG, compressPNG ? "true" : "false");
 		const jpegQuality = pkg.getJpegQuality();
@@ -14159,21 +14236,26 @@ var ProjectWriter = class {
 		});
 		if (publishAtlases.length > 0) publishAttrs.atlas = publishAtlases;
 		const packageDescriptorPath = fs.join(pkgDir, "package.xml");
-		await fs.writeFile(packageDescriptorPath, this._renderPackageDescriptionXml(packageDescriptionAttrs, mainResources, publishAttrs));
+		await fs.writeFile(packageDescriptorPath, this._renderPackageDescriptionXml(packageDescriptionAttrs, mainFolders, mainResources, publishAttrs));
 		currentSourceFilePaths.add(packageDescriptorPath);
+		await this._writeResourceFolders(mainFolders, pkgDir, currentResourceFolderPaths);
 		for (const comp of mainResources.filter((resource) => resource.propertyType === "Component")) {
 			currentSourceFilePaths.add(fs.join(pkgDir, this._componentSourceRelativePath(comp)));
 			await writeComponent(this._fs, comp, pkgDir, this._componentSourceRelativePath(comp));
 		}
 		await this._writeResourceSourceFiles(mainResources, pkgDir, currentSourceFilePaths);
-		for (const [branchName, branchResources] of resourcesByBranch) {
+		const branchNames = new Set([...resourcesByBranch.keys(), ...foldersByBranch.keys()]);
+		for (const branchName of branchNames) {
 			if (!branchName) continue;
+			const branchResources = resourcesByBranch.get(branchName) ?? [];
+			const branchFolders = foldersByBranch.get(branchName) ?? [];
 			this._assertSafePathSegment(branchName, "branch name");
 			const branchPkgDir = fs.join(basePath, `assets_${branchName}`, pkg.getName());
 			await fs.mkdir(branchPkgDir);
 			const branchDescriptorPath = fs.join(branchPkgDir, "package_branch.xml");
-			await fs.writeFile(branchDescriptorPath, this._renderBranchDescriptionXml(branchResources));
+			await fs.writeFile(branchDescriptorPath, this._renderBranchDescriptionXml(branchFolders, branchResources));
 			currentSourceFilePaths.add(branchDescriptorPath);
+			await this._writeResourceFolders(branchFolders, branchPkgDir, currentResourceFolderPaths);
 			for (const comp of branchResources.filter((resource) => resource.propertyType === "Component")) {
 				currentSourceFilePaths.add(fs.join(branchPkgDir, this._componentSourceRelativePath(comp)));
 				await writeComponent(this._fs, comp, branchPkgDir, this._componentSourceRelativePath(comp));
@@ -14181,6 +14263,14 @@ var ProjectWriter = class {
 			await this._writeResourceSourceFiles(branchResources, branchPkgDir, currentSourceFilePaths);
 		}
 	}
+	async _writeResourceFolders(folders, packageDir, currentResourceFolderPaths) {
+		for (const folder of folders) {
+			const relativePath = this._normalizeSourceRelativePath(folder.path);
+			const targetPath = this._fs.join(packageDir, relativePath);
+			await this._fs.mkdir(targetPath);
+			currentResourceFolderPaths.add(targetPath);
+		}
+	}
 	async _writeResourceSourceFiles(resources, packageDir, currentSourceFilePaths) {
 		const fs = this._fs;
 		for (const resource of resources) {
@@ -14208,18 +14298,41 @@ var ProjectWriter = class {
 			await fs.unlink(filePath);
 		}
 	}
+	async _removeStaleResourceFolders(currentResourceFolderPaths, staleResourceFolderPaths) {
+		const candidates = [...staleResourceFolderPaths].filter((folderPath) => !currentResourceFolderPaths.has(folderPath)).sort((left, right) => right.length - left.length);
+		if (candidates.length === 0) return;
+		if (!this._fs.rmdir) throw new Error("Project resource folder cleanup requires a FileSystem.rmdir() implementation.");
+		for (const folderPath of candidates) {
+			if (!await this._fs.exists(folderPath)) continue;
+			await this._fs.rmdir(folderPath);
+		}
+	}
 	_assertPackageOutputTargets(pkg) {
 		this._assertSafePathSegment(pkg.getName(), "package name");
 		const resourcesByBranch = /* @__PURE__ */ new Map();
+		const foldersByBranch = /* @__PURE__ */ new Map();
 		for (const resource of pkg.listResources()) {
 			const branchName = resource.getBranch?.() ?? "";
 			const bucket = resourcesByBranch.get(branchName) ?? [];
 			bucket.push(resource);
 			resourcesByBranch.set(branchName, bucket);
 		}
-		for (const [branchName, resources] of resourcesByBranch) {
+		for (const folder of pkg.listResourceFolders()) {
+			const bucket = foldersByBranch.get(folder.branch) ?? [];
+			bucket.push(folder);
+			foldersByBranch.set(folder.branch, bucket);
+		}
+		for (const branchName of new Set([...resourcesByBranch.keys(), ...foldersByBranch.keys()])) {
+			const resources = resourcesByBranch.get(branchName) ?? [];
 			if (branchName) this._assertSafePathSegment(branchName, "branch name");
 			const targets = new Map([[branchName ? "package_branch.xml" : "package.xml", "package descriptor"]]);
+			for (const folder of foldersByBranch.get(branchName) ?? []) {
+				const target = this._normalizeSourceRelativePath(folder.path);
+				if (!target) throw new Error(`Package "${pkg.getName()}" cannot declare the resource root as a folder.`);
+				const previous = targets.get(target);
+				if (previous) throw new Error(`Package "${pkg.getName()}" output "${target}" conflicts with ${previous}.`);
+				targets.set(target, `resource folder "${folder.path}"`);
+			}
 			for (const resource of resources) {
 				const target = resource.propertyType === "Component" ? this._componentSourceRelativePath(resource) : this._resourceSourceRelativePath(resource, this._resourceFileName(resource));
 				if (!target) continue;
@@ -14237,6 +14350,13 @@ var ProjectWriter = class {
 		const assetRoot = source.branch ? `assets_${source.branch}` : "assets";
 		return this._fs.join(basePath, assetRoot, source.packageName, relativePath);
 	}
+	_projectResourceFolderPath(basePath, folder) {
+		this._assertSafePathSegment(folder.packageName, "resource folder package name");
+		if (folder.branch) this._assertSafePathSegment(folder.branch, "resource folder branch name");
+		const relativePath = this._normalizeSourceRelativePath(folder.path);
+		const assetRoot = folder.branch ? `assets_${folder.branch}` : "assets";
+		return this._fs.join(basePath, assetRoot, folder.packageName, relativePath);
+	}
 	_resourceSourceRelativePath(resource, fileName) {
 		if (!fileName) return "";
 		this._assertSafePathSegment(fileName, "resource file name");
@@ -14258,12 +14378,13 @@ var ProjectWriter = class {
 		if (segments.some((segment) => segment === "." || segment === ".." || segment.includes(":"))) throw new Error(`Invalid project source path "${value}".`);
 		return segments.join("/");
 	}
-	_renderPackageDescriptionXml(packageDescriptionAttrs, resources, publishAttrs) {
+	_renderPackageDescriptionXml(packageDescriptionAttrs, folders, resources, publishAttrs) {
 		const publishNodeAttrs = Object.fromEntries(Object.entries(publishAttrs).filter(([key]) => key !== "atlas"));
 		const lines = [
 			"<?xml version=\"1.0\" encoding=\"utf-8\"?>",
 			`<packageDescription${renderXmlAttrs(packageDescriptionAttrs)}>`,
 			"  <resources>",
+			...this._renderPackageResourceFolderLines(folders, "    "),
 			...this._renderPackageResourceLines(resources, "    "),
 			"  </resources>",
 			`  <publish${renderXmlAttrs(publishNodeAttrs)}>`
@@ -14274,16 +14395,29 @@ var ProjectWriter = class {
 		lines.push("</packageDescription>");
 		return `${lines.join("\n")}\n`;
 	}
-	_renderBranchDescriptionXml(resources) {
+	_renderBranchDescriptionXml(folders, resources) {
 		return `${[
 			"<?xml version=\"1.0\" encoding=\"utf-8\"?>",
 			"<branchDescription>",
 			"  <resources>",
+			...this._renderPackageResourceFolderLines(folders, "    "),
 			...this._renderPackageResourceLines(resources, "    "),
 			"  </resources>",
 			"</branchDescription>"
 		].join("\n")}\n`;
 	}
+	_renderPackageResourceFolderLines(folders, indent) {
+		return [...folders].filter((folder) => folder.favorite || folder.atlas).sort((left, right) => left.path.localeCompare(right.path)).map((folder) => {
+			const attrs = {};
+			const id = folder.branch ? `/:${folder.branch}${folder.path}` : folder.path;
+			writeXmlAttr(attrs, PROJECT_XML_PROTOCOL.packageResourceFolder.attrs.id, id);
+			writeXmlAttr(attrs, PROJECT_XML_PROTOCOL.packageResourceFolder.attrs.name, resourceFolderName(folder.path));
+			writeXmlAttr(attrs, PROJECT_XML_PROTOCOL.packageResourceFolder.attrs.path, resourceFolderParentPath(folder.path));
+			if (folder.favorite) writeXmlAttr(attrs, PROJECT_XML_PROTOCOL.packageResourceFolder.attrs.favorite, "true");
+			if (folder.atlas) writeXmlAttr(attrs, PROJECT_XML_PROTOCOL.packageResourceFolder.attrs.atlas, folder.atlas);
+			return `${indent}<folder${renderXmlAttrs(attrs)}/>`;
+		});
+	}
 	_renderPackageResourceLines(resources, indent) {
 		return this._orderedPackageResources(resources).map((resource) => {
 			const serialized = this._serializePackageResourceEntry(resource);
@@ -26308,6 +26442,9 @@ var NodeIO = class extends PlatformIO {
 			async unlink(filePath) {
 				await fs$1.unlink(filePath);
 			},
+			async rmdir(dirPath) {
+				await fs$1.rmdir(dirPath);
+			},
 			join(...paths) {
 				return path$1.join(...paths);
 			},

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openfairygui/cli",
-  "version": "0.2.0-alpha.29",
+  "version": "0.2.0-alpha.30",
   "description": "FairyGUI Headless Authoring SDK — command-line interface.",
   "author": "OpenFairyGUI Contributors",
   "license": "MIT",
@@ -33,13 +33,13 @@
     "restore"
   ],
   "devDependencies": {
-    "@openfairygui/core": "0.2.0-alpha.29",
-    "@openfairygui/functions": "0.2.0-alpha.29"
+    "@openfairygui/core": "0.2.0-alpha.30",
+    "@openfairygui/functions": "0.2.0-alpha.30"
   },
   "dependencies": {
     "commander": "^14.0.2",
     "jiti": "^2.7.0",
-    "@openfairygui/backend": "0.2.0-alpha.29"
+    "@openfairygui/backend": "0.2.0-alpha.30"
   },
   "optionalDependencies": {
     "sharp": ">=0.33.0"