@playdrop/playdrop-cli 0.3.1-build.1

package/dist/catalogue.js

@@ -0,0 +1,1289 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateAppMetadata = validateAppMetadata;
+exports.resolveCatalogueEntries = resolveCatalogueEntries;
+exports.resolveWorkspaceApp = resolveWorkspaceApp;
+exports.formatMetadataWarnings = formatMetadataWarnings;
+exports.formatMissingMetadataWarnings = formatMissingMetadataWarnings;
+exports.findAppTaskByFile = findAppTaskByFile;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const types_1 = require("@playdrop/types");
+const catalogue_utils_1 = require("./catalogue-utils");
+const HEX_COLOR_REGEX = /^#?(?:[0-9a-fA-F]{6})$/;
+const SEMVER_REGEX = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/;
+const ASSET_CATEGORY_SET = new Set(types_1.ASSET_CATEGORY_VALUES);
+const ASSET_SUBCATEGORY_SET_BY_CATEGORY = types_1.ASSET_SUBCATEGORY_DEFINITIONS.reduce((acc, definition) => {
+    if (!acc[definition.category]) {
+        acc[definition.category] = new Set();
+    }
+    acc[definition.category].add(definition.subcategory);
+    return acc;
+}, {});
+/**
+ * Validates a listing asset path:
+ * - Must exist
+ * - Must be a file (not a directory)
+ * - Must be within the base directory (no path traversal)
+ *
+ * @returns Error message if invalid, undefined if valid
+ */
+function validateListingAssetPath(baseDir, relativePath, fieldName) {
+    const absolutePath = (0, node_path_1.resolve)(baseDir, relativePath);
+    // Path traversal check: resolved path must be within baseDir
+    const normalizedBase = (0, node_fs_1.realpathSync)(baseDir);
+    let normalizedPath;
+    try {
+        // If path doesn't exist, realpath will throw - check existence first
+        if (!(0, node_fs_1.existsSync)(absolutePath)) {
+            return `${fieldName} not found at ${absolutePath}`;
+        }
+        normalizedPath = (0, node_fs_1.realpathSync)(absolutePath);
+    }
+    catch {
+        return `${fieldName} not found at ${absolutePath}`;
+    }
+    if (!normalizedPath.startsWith(normalizedBase + node_path_1.sep) && normalizedPath !== normalizedBase) {
+        return `${fieldName} path "${relativePath}" resolves outside the project directory`;
+    }
+    // Must be a file, not a directory
+    try {
+        if (!(0, node_fs_1.statSync)(absolutePath).isFile()) {
+            return `${fieldName} must be a file, not a directory: ${absolutePath}`;
+        }
+    }
+    catch {
+        return `${fieldName} not accessible at ${absolutePath}`;
+    }
+    return undefined;
+}
+/**
+ * Resolves a listing asset path after validation.
+ */
+function resolveListingAssetPath(baseDir, relativePath) {
+    return (0, node_path_1.resolve)(baseDir, relativePath);
+}
+function normalizeRelativePath(root, target) {
+    const rel = (0, node_path_1.relative)(root, target).split(node_path_1.sep).join('/');
+    return rel.replace(/^\/+/, '');
+}
+function tryRealpath(path) {
+    try {
+        return (0, node_fs_1.realpathSync)(path);
+    }
+    catch {
+        return null;
+    }
+}
+function normalizePathForComparison(path) {
+    const actual = tryRealpath(path) ?? (0, node_path_1.resolve)(path);
+    return actual.split(node_path_1.sep).join('/');
+}
+function shouldSkipDirectory(name) {
+    if (!name)
+        return true;
+    if (name === '.' || name === '..')
+        return true;
+    if (name.startsWith('.'))
+        return true;
+    return name === 'node_modules';
+}
+function readCatalogueFile(rootDir, filePath) {
+    try {
+        const raw = (0, node_fs_1.readFileSync)(filePath, 'utf8');
+        const parsed = raw.trim() ? JSON.parse(raw) : {};
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+            return { error: 'catalogue.json must contain a JSON object' };
+        }
+        if (parsed.schemaVersion !== 2) {
+            return { error: 'catalogue.json must set "schemaVersion": 2' };
+        }
+        const forbiddenKeys = ['avatars', 'humanoids', 'creatures', 'blocks', 'games'];
+        for (const key of forbiddenKeys) {
+            if (Object.prototype.hasOwnProperty.call(parsed, key)) {
+                return { error: `catalogue.json schema v2 forbids top-level "${key}"` };
+            }
+        }
+        const allowedKeys = new Set(['schemaVersion', 'apps', 'assets', 'assetPacks']);
+        const unknownKeys = Object.keys(parsed).filter((key) => !allowedKeys.has(key));
+        if (unknownKeys.length > 0) {
+            return {
+                error: `catalogue.json schema v2 contains unsupported top-level key "${unknownKeys[0]}"`,
+            };
+        }
+        const directory = (0, node_path_1.dirname)(filePath);
+        const relativePath = (0, node_path_1.relative)(rootDir, filePath) || 'catalogue.json';
+        return {
+            file: {
+                absolutePath: filePath,
+                relativePath: relativePath.replace(/\\/g, '/'),
+                directory,
+                data: parsed,
+            },
+        };
+    }
+    catch (error) {
+        return { error: `Invalid catalogue.json (${error?.message || 'failed to parse JSON'})` };
+    }
+}
+function walkCatalogueTree(rootDir) {
+    const files = [];
+    const errors = [];
+    let rootRealPath = rootDir;
+    try {
+        rootRealPath = (0, node_fs_1.realpathSync)(rootDir);
+    }
+    catch {
+        // ignore
+    }
+    const stack = [{ realPath: rootRealPath, displayPath: rootDir }];
+    const visited = new Set();
+    while (stack.length > 0) {
+        const { realPath, displayPath } = stack.pop();
+        if (visited.has(realPath))
+            continue;
+        visited.add(realPath);
+        const candidate = (0, node_path_1.join)(displayPath, 'catalogue.json');
+        if ((0, node_fs_1.existsSync)(candidate) && (0, node_fs_1.statSync)(candidate).isFile()) {
+            const result = readCatalogueFile(rootDir, candidate);
+            if (result.error) {
+                errors.push(`[${normalizeRelativePath(rootDir, candidate) || 'catalogue.json'}] ${result.error}`);
+            }
+            else if (result.file) {
+                files.push(result.file);
+            }
+        }
+        let entries = [];
+        try {
+            entries = (0, node_fs_1.readdirSync)(displayPath, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            if (!entry.isDirectory())
+                continue;
+            if (shouldSkipDirectory(entry.name))
+                continue;
+            const nextDisplayPath = (0, node_path_1.join)(displayPath, entry.name);
+            let nextRealPath = nextDisplayPath;
+            try {
+                nextRealPath = (0, node_fs_1.realpathSync)(nextDisplayPath);
+            }
+            catch {
+                // ignore
+            }
+            if (visited.has(nextRealPath)) {
+                continue;
+            }
+            stack.push({ realPath: nextRealPath, displayPath: nextDisplayPath });
+        }
+    }
+    files.sort((a, b) => a.relativePath.localeCompare(b.relativePath));
+    return { files, errors };
+}
+const packageJsonCache = new Map();
+function resolvePackageJson(projectDir) {
+    const candidate = (0, node_path_1.join)(projectDir, 'package.json');
+    if (!(0, node_fs_1.existsSync)(candidate)) {
+        return null;
+    }
+    try {
+        const stats = (0, node_fs_1.statSync)(candidate);
+        return stats.isFile() ? candidate : null;
+    }
+    catch {
+        return null;
+    }
+}
+function readPackageJsonManifest(packageJsonPath) {
+    if (packageJsonCache.has(packageJsonPath)) {
+        return packageJsonCache.get(packageJsonPath);
+    }
+    try {
+        const raw = (0, node_fs_1.readFileSync)(packageJsonPath, 'utf8');
+        const parsed = raw.trim() ? JSON.parse(raw) : {};
+        packageJsonCache.set(packageJsonPath, parsed);
+        return parsed;
+    }
+    catch (error) {
+        throw new Error(error?.message || 'failed to parse package.json');
+    }
+}
+function collectMissingMetadata(entry) {
+    const missing = [];
+    if (typeof entry.displayName !== 'string' || !entry.displayName.trim()) {
+        missing.push('displayName');
+    }
+    if (typeof entry.description !== 'string' || !entry.description.trim()) {
+        missing.push('description');
+    }
+    const emojiProvided = Object.prototype.hasOwnProperty.call(entry, 'emoji');
+    if (!emojiProvided) {
+        missing.push('emoji');
+    }
+    else {
+        const emojiValue = entry.emoji;
+        if (emojiValue !== null) {
+            if (typeof emojiValue !== 'string' || !emojiValue.trim()) {
+                missing.push('emoji');
+            }
+        }
+    }
+    const colorProvided = Object.prototype.hasOwnProperty.call(entry, 'color');
+    if (!colorProvided) {
+        missing.push('color');
+    }
+    else {
+        const colorValue = entry.color;
+        if (colorValue !== null) {
+            if (typeof colorValue !== 'string' || !colorValue.trim()) {
+                missing.push('color');
+            }
+        }
+    }
+    return missing;
+}
+function formatMissingMetadata(missing) {
+    if (missing.length === 0)
+        return '';
+    if (missing.length === 1)
+        return `no ${missing[0]} provided`;
+    if (missing.length === 2)
+        return `no ${missing[0]} or ${missing[1]} provided`;
+    const last = missing[missing.length - 1];
+    const initial = missing.slice(0, -1).join(', ');
+    return `no ${initial}, or ${last} provided`;
+}
+function normalizeAssetVisibilityValue(raw, errors, label) {
+    if (typeof raw !== 'string' || raw.trim().length === 0) {
+        return undefined;
+    }
+    const normalized = raw.trim().toUpperCase();
+    if (normalized !== 'PUBLIC' && normalized !== 'PRIVATE') {
+        errors.push(`[${label}] visibility must be PUBLIC or PRIVATE.`);
+        return undefined;
+    }
+    return normalized;
+}
+function normalizeAssetCategoryValue(raw, errors, label) {
+    if (typeof raw !== 'string' || raw.trim().length === 0) {
+        errors.push(`${label} must define category.`);
+        return null;
+    }
+    const normalized = raw.trim().toUpperCase();
+    if (!ASSET_CATEGORY_SET.has(normalized)) {
+        errors.push(`${label} uses unsupported category "${raw}".`);
+        return null;
+    }
+    return normalized;
+}
+function normalizeAssetSubcategoryValue(raw, category, errors, label) {
+    if (typeof raw !== 'string' || raw.trim().length === 0) {
+        errors.push(`${label} must define subcategory.`);
+        return null;
+    }
+    const normalized = (0, types_1.normalizeAssetSubcategory)(raw);
+    if (!(0, types_1.isValidAssetSubcategorySlug)(normalized)) {
+        errors.push(`${label} uses invalid subcategory "${raw}".`);
+        return null;
+    }
+    const allowedSubcategories = ASSET_SUBCATEGORY_SET_BY_CATEGORY[category] ?? null;
+    if (!allowedSubcategories || !allowedSubcategories.has(normalized)) {
+        errors.push(`${label} uses unsupported subcategory "${raw}" for category "${category}".`);
+        return null;
+    }
+    return normalized;
+}
+function validateAppMetadata(entry) {
+    const warnings = [];
+    const errors = [];
+    const missingFields = collectMissingMetadata(entry);
+    if (missingFields.length > 0) {
+        warnings.push(formatMissingMetadata(missingFields));
+    }
+    let emoji = entry.emoji;
+    if (Object.prototype.hasOwnProperty.call(entry, 'emoji')) {
+        if (emoji !== null && typeof emoji === 'string') {
+            const trimmed = emoji.trim();
+            if (!trimmed) {
+                emoji = null;
+            }
+            else if (Array.from(trimmed).length > 4) {
+                errors.push('emoji must be a single character');
+            }
+            else {
+                emoji = trimmed;
+            }
+        }
+        else if (emoji !== null) {
+            errors.push('emoji must be a string or null');
+        }
+    }
+    let color = entry.color;
+    if (Object.prototype.hasOwnProperty.call(entry, 'color')) {
+        if (color !== null && typeof color === 'string') {
+            const trimmed = color.trim();
+            if (!trimmed) {
+                color = null;
+            }
+            else if (!HEX_COLOR_REGEX.test(trimmed)) {
+                errors.push('color must be a hex RGB value like #FFAA00');
+            }
+            else {
+                color = trimmed.startsWith('#') ? trimmed.toUpperCase() : `#${trimmed.toUpperCase()}`;
+            }
+        }
+        else if (color !== null) {
+            errors.push('color must be a string or null');
+        }
+    }
+    let type;
+    if (typeof entry.type === 'string' && entry.type.trim()) {
+        const parsedType = (0, types_1.parseAppType)(entry.type.trim());
+        if (!parsedType) {
+            errors.push(`type must be one of ${types_1.APP_TYPE_VALUES.join(', ')}`);
+        }
+        else {
+            type = parsedType;
+        }
+    }
+    let displayName;
+    if (typeof entry.displayName === 'string' && entry.displayName.trim()) {
+        displayName = entry.displayName.trim();
+    }
+    let description;
+    if (typeof entry.description === 'string') {
+        description = entry.description;
+    }
+    let surfaceTargetsList = [];
+    let surfaceTargetsMap = { desktop: false, mobileLandscape: false, mobilePortrait: false };
+    try {
+        const parsed = (0, catalogue_utils_1.parseSurfaceTargets)(entry.surfaceTargets);
+        surfaceTargetsList = parsed.list;
+        surfaceTargetsMap = { ...parsed.map };
+    }
+    catch (error) {
+        errors.push(error?.message || 'invalid surfaceTargets');
+    }
+    return {
+        displayName,
+        description,
+        type,
+        emoji,
+        color,
+        surfaceTargets: surfaceTargetsList,
+        surfaceTargetMap: surfaceTargetsMap,
+        missingFields,
+        warnings,
+        errors,
+    };
+}
+function buildAppTasks(rootDir, catalogues, options) {
+    const tasks = [];
+    const warnings = [];
+    const errors = [];
+    const seen = new Map();
+    const filterName = options.filterName ? options.filterName.trim() : '';
+    const filterFile = options.filterFile ? normalizePathForComparison(options.filterFile) : '';
+    for (const file of catalogues) {
+        const label = file.relativePath || 'catalogue.json';
+        const rawApps = Array.isArray(file.data.apps) ? file.data.apps : [];
+        if (rawApps.length === 0) {
+            const legacyGames = Array.isArray(file.data.games);
+            if (legacyGames) {
+                errors.push(`[${label}] Rename the legacy "games" array to "apps" before uploading.`);
+            }
+            continue;
+        }
+        for (const entry of rawApps) {
+            if (!entry || typeof entry !== 'object') {
+                errors.push(`[${label}] Invalid app entry; expected object.`);
+                continue;
+            }
+            const rawName = typeof entry.name === 'string' ? entry.name.trim() : '';
+            if (!rawName) {
+                errors.push(`[${label}] App entry is missing a name.`);
+                continue;
+            }
+            const fileField = typeof entry.file === 'string' && entry.file.trim().length > 0
+                ? entry.file.trim()
+                : `${rawName}.html`;
+            const absoluteFilePath = (0, node_path_1.resolve)(file.directory, fileField);
+            const normalizedFile = normalizePathForComparison(absoluteFilePath);
+            const matchName = filterName ? rawName === filterName : true;
+            const matchFile = filterFile ? normalizedFile === filterFile : true;
+            if (!matchName || !matchFile) {
+                continue;
+            }
+            if (seen.has(rawName)) {
+                errors.push(`[${label}] Duplicate app name "${rawName}" also defined in [${seen.get(rawName)}]`);
+                continue;
+            }
+            seen.set(rawName, label);
+            // Check for external mode early (before file validation)
+            const rawExternalUrlEarly = typeof entry.externalUrl === 'string' ? entry.externalUrl.trim() : '';
+            const rawHostingModeEarly = typeof entry.hostingMode === 'string' ? entry.hostingMode.trim().toUpperCase() : '';
+            const isExternalMode = rawHostingModeEarly === 'EXTERNAL' || (rawExternalUrlEarly && rawExternalUrlEarly.startsWith('https://'));
+            // Only validate file path for non-external apps
+            if (!isExternalMode) {
+                const relativeToProject = (0, node_path_1.relative)(file.directory, absoluteFilePath);
+                if (relativeToProject.startsWith('..')) {
+                    errors.push(`[${label}] Skipping ${rawName}: file path escapes project directory (${fileField}).`);
+                    continue;
+                }
+            }
+            const packageJsonPath = resolvePackageJson(file.directory);
+            const isTypescriptProject = Boolean(packageJsonPath);
+            let packageManifest = null;
+            let hasValidateScript = false;
+            let hasFormatScript = false;
+            if (isTypescriptProject && packageJsonPath) {
+                try {
+                    packageManifest = readPackageJsonManifest(packageJsonPath);
+                    const scripts = packageManifest?.scripts;
+                    if (scripts && typeof scripts.validate === 'string' && scripts.validate.trim().length > 0) {
+                        hasValidateScript = true;
+                    }
+                    if (scripts && typeof scripts.format === 'string' && scripts.format.trim().length > 0) {
+                        hasFormatScript = true;
+                    }
+                }
+                catch (error) {
+                    errors.push(`[${label}] Skipping ${rawName}: failed to read package.json (${error?.message || 'unknown error'}).`);
+                    continue;
+                }
+            }
+            // Only validate file existence for non-external apps
+            if (!isExternalMode) {
+                if (!isTypescriptProject) {
+                    if (!(0, node_fs_1.existsSync)(absoluteFilePath)) {
+                        errors.push(`[${label}] Skipping ${rawName}: file not found at ${absoluteFilePath}`);
+                        continue;
+                    }
+                    if (!(0, node_fs_1.statSync)(absoluteFilePath).isFile()) {
+                        errors.push(`[${label}] Skipping ${rawName}: expected a file at ${absoluteFilePath}`);
+                        continue;
+                    }
+                }
+                else if ((0, node_fs_1.existsSync)(absoluteFilePath) && !(0, node_fs_1.statSync)(absoluteFilePath).isFile()) {
+                    errors.push(`[${label}] Skipping ${rawName}: expected a file at ${absoluteFilePath}`);
+                    continue;
+                }
+            }
+            const metadata = validateAppMetadata(entry);
+            if (metadata.errors.length > 0) {
+                errors.push(`[${label}] Skipping ${rawName}: ${metadata.errors.join('; ')}`);
+                continue;
+            }
+            if (metadata.warnings.length > 0) {
+                warnings.push(`${label} (${metadata.warnings.join('; ')})`);
+            }
+            if (isTypescriptProject && !hasValidateScript) {
+                warnings.push(`${label} (${rawName}: package.json missing "validate" script)`);
+            }
+            if (isTypescriptProject && !hasFormatScript) {
+                warnings.push(`${label} (${rawName}: package.json missing "format" script)`);
+            }
+            // Handle optional ecs and server paths
+            let ecsPath;
+            let serverPath;
+            const ecsField = typeof entry.ecs === 'string' ? entry.ecs.trim() : '';
+            if (ecsField) {
+                const absoluteEcsPath = (0, node_path_1.resolve)(file.directory, ecsField);
+                const relativeToProject = (0, node_path_1.relative)(file.directory, absoluteEcsPath);
+                if (relativeToProject.startsWith('..')) {
+                    errors.push(`[${label}] Skipping ${rawName}: ecs path escapes project directory (${ecsField}).`);
+                    continue;
+                }
+                if (!(0, node_fs_1.existsSync)(absoluteEcsPath)) {
+                    errors.push(`[${label}] Skipping ${rawName}: ecs file not found at ${absoluteEcsPath}`);
+                    continue;
+                }
+                if (!(0, node_fs_1.statSync)(absoluteEcsPath).isFile()) {
+                    errors.push(`[${label}] Skipping ${rawName}: expected a file at ${absoluteEcsPath}`);
+                    continue;
+                }
+                ecsPath = absoluteEcsPath;
+            }
+            const serverField = typeof entry.server === 'string' ? entry.server.trim() : '';
+            if (serverField) {
+                const absoluteServerPath = (0, node_path_1.resolve)(file.directory, serverField);
+                const relativeToProject = (0, node_path_1.relative)(file.directory, absoluteServerPath);
+                if (relativeToProject.startsWith('..')) {
+                    errors.push(`[${label}] Skipping ${rawName}: server path escapes project directory (${serverField}).`);
+                    continue;
+                }
+                if (!(0, node_fs_1.existsSync)(absoluteServerPath)) {
+                    errors.push(`[${label}] Skipping ${rawName}: server file not found at ${absoluteServerPath}`);
+                    continue;
+                }
+                if (!(0, node_fs_1.statSync)(absoluteServerPath).isFile()) {
+                    errors.push(`[${label}] Skipping ${rawName}: expected a file at ${absoluteServerPath}`);
+                    continue;
+                }
+                serverPath = absoluteServerPath;
+            }
+            // Parse versioning fields (required in schema v2)
+            let version;
+            const rawVersion = typeof entry.version === 'string' ? entry.version.trim() : '';
+            if (!rawVersion) {
+                errors.push(`[${label}] Skipping ${rawName}: app version is required in schema v2 (e.g., "1.0.0").`);
+                continue;
+            }
+            if (!SEMVER_REGEX.test(rawVersion)) {
+                errors.push(`[${label}] Skipping ${rawName}: version must be in Major.Minor.Patch format (e.g., "1.0.0").`);
+                continue;
+            }
+            version = rawVersion;
+            const releaseNotes = typeof entry.releaseNotes === 'string' ? entry.releaseNotes : undefined;
+            let versionVisibility;
+            const rawVisibility = typeof entry.visibility === 'string' ? entry.visibility.trim().toUpperCase() : '';
+            if (rawVisibility) {
+                if (!types_1.APP_VERSION_VISIBILITY_VALUES.includes(rawVisibility)) {
+                    errors.push(`[${label}] Skipping ${rawName}: visibility must be one of ${types_1.APP_VERSION_VISIBILITY_VALUES.join(', ')}.`);
+                    continue;
+                }
+                versionVisibility = rawVisibility;
+            }
+            let hostingMode;
+            const rawHostingMode = typeof entry.hostingMode === 'string' ? entry.hostingMode.trim().toUpperCase() : '';
+            if (rawHostingMode) {
+                if (!types_1.APP_HOSTING_MODE_VALUES.includes(rawHostingMode)) {
+                    errors.push(`[${label}] Skipping ${rawName}: hostingMode must be one of ${types_1.APP_HOSTING_MODE_VALUES.join(', ')}.`);
+                    continue;
+                }
+                hostingMode = rawHostingMode;
+            }
+            let externalUrl;
+            const rawExternalUrl = typeof entry.externalUrl === 'string' ? entry.externalUrl.trim() : '';
+            if (rawExternalUrl) {
+                if (!rawExternalUrl.startsWith('https://')) {
+                    errors.push(`[${label}] Skipping ${rawName}: externalUrl must be an HTTPS URL.`);
+                    continue;
+                }
+                externalUrl = rawExternalUrl;
+            }
+            // Validate hostingMode / externalUrl consistency
+            if (hostingMode === 'EXTERNAL' && !externalUrl) {
+                errors.push(`[${label}] Skipping ${rawName}: externalUrl is required when hostingMode is EXTERNAL.`);
+                continue;
+            }
+            if (externalUrl && hostingMode !== 'EXTERNAL') {
+                // Auto-set hostingMode to EXTERNAL if externalUrl is provided
+                hostingMode = 'EXTERNAL';
+            }
+            // Parse username field (admin-only)
+            let username;
+            const rawUsername = typeof entry.username === 'string' ? entry.username.trim() : '';
+            if (rawUsername) {
+                username = rawUsername;
+            }
+            // Parse listing assets
+            let listing;
+            const rawListing = entry.listing;
+            let listingValidationFailed = false;
+            if (rawListing && typeof rawListing === 'object') {
+                const resolvedListing = {
+                    screenshotPortraitPaths: [],
+                    screenshotLandscapePaths: [],
+                    videoPortraitPaths: [],
+                    videoLandscapePaths: [],
+                };
+                // Icon
+                if (typeof rawListing.icon === 'string' && rawListing.icon.trim()) {
+                    const validationError = validateListingAssetPath(file.directory, rawListing.icon.trim(), 'listing.icon');
+                    if (validationError) {
+                        errors.push(`[${label}] Skipping ${rawName}: ${validationError}`);
+                        listingValidationFailed = true;
+                    }
+                    else {
+                        resolvedListing.iconPath = resolveListingAssetPath(file.directory, rawListing.icon.trim());
+                    }
+                }
+                // Hero images
+                if (!listingValidationFailed && typeof rawListing.heroPortrait === 'string' && rawListing.heroPortrait.trim()) {
+                    const validationError = validateListingAssetPath(file.directory, rawListing.heroPortrait.trim(), 'listing.heroPortrait');
+                    if (validationError) {
+                        errors.push(`[${label}] Skipping ${rawName}: ${validationError}`);
+                        listingValidationFailed = true;
+                    }
+                    else {
+                        resolvedListing.heroPortraitPath = resolveListingAssetPath(file.directory, rawListing.heroPortrait.trim());
+                    }
+                }
+                if (!listingValidationFailed && typeof rawListing.heroLandscape === 'string' && rawListing.heroLandscape.trim()) {
+                    const validationError = validateListingAssetPath(file.directory, rawListing.heroLandscape.trim(), 'listing.heroLandscape');
+                    if (validationError) {
+                        errors.push(`[${label}] Skipping ${rawName}: ${validationError}`);
+                        listingValidationFailed = true;
+                    }
+                    else {
+                        resolvedListing.heroLandscapePath = resolveListingAssetPath(file.directory, rawListing.heroLandscape.trim());
+                    }
+                }
+                // Screenshots
+                if (!listingValidationFailed && Array.isArray(rawListing.screenshotsPortrait)) {
+                    for (const p of rawListing.screenshotsPortrait) {
+                        if (typeof p === 'string' && p.trim()) {
+                            const validationError = validateListingAssetPath(file.directory, p.trim(), 'listing.screenshotsPortrait item');
+                            if (validationError) {
+                                errors.push(`[${label}] Skipping ${rawName}: ${validationError}`);
+                                listingValidationFailed = true;
+                                break;
+                            }
+                            resolvedListing.screenshotPortraitPaths.push(resolveListingAssetPath(file.directory, p.trim()));
+                        }
+                    }
+                }
+                if (!listingValidationFailed && Array.isArray(rawListing.screenshotsLandscape)) {
+                    for (const p of rawListing.screenshotsLandscape) {
+                        if (typeof p === 'string' && p.trim()) {
+                            const validationError = validateListingAssetPath(file.directory, p.trim(), 'listing.screenshotsLandscape item');
+                            if (validationError) {
+                                errors.push(`[${label}] Skipping ${rawName}: ${validationError}`);
+                                listingValidationFailed = true;
+                                break;
+                            }
+                            resolvedListing.screenshotLandscapePaths.push(resolveListingAssetPath(file.directory, p.trim()));
+                        }
+                    }
+                }
+                // Videos
+                if (!listingValidationFailed && Array.isArray(rawListing.videosPortrait)) {
+                    for (const p of rawListing.videosPortrait) {
+                        if (typeof p === 'string' && p.trim()) {
+                            const validationError = validateListingAssetPath(file.directory, p.trim(), 'listing.videosPortrait item');
+                            if (validationError) {
+                                errors.push(`[${label}] Skipping ${rawName}: ${validationError}`);
+                                listingValidationFailed = true;
+                                break;
+                            }
+                            resolvedListing.videoPortraitPaths.push(resolveListingAssetPath(file.directory, p.trim()));
+                        }
+                    }
+                }
+                if (!listingValidationFailed && Array.isArray(rawListing.videosLandscape)) {
+                    for (const p of rawListing.videosLandscape) {
+                        if (typeof p === 'string' && p.trim()) {
+                            const validationError = validateListingAssetPath(file.directory, p.trim(), 'listing.videosLandscape item');
+                            if (validationError) {
+                                errors.push(`[${label}] Skipping ${rawName}: ${validationError}`);
+                                listingValidationFailed = true;
+                                break;
+                            }
+                            resolvedListing.videoLandscapePaths.push(resolveListingAssetPath(file.directory, p.trim()));
+                        }
+                    }
+                }
+                if (listingValidationFailed) {
+                    continue;
+                }
+                listing = resolvedListing;
+            }
+            const usesAssets = Array.isArray(entry.uses?.assets)
+                ? entry.uses.assets.filter((value) => typeof value === 'string' && value.trim().length > 0)
+                : [];
+            const usesPacks = Array.isArray(entry.uses?.packs)
+                ? entry.uses.packs.filter((value) => typeof value === 'string' && value.trim().length > 0)
+                : [];
+            const graphRelations = [];
+            if (Array.isArray(entry.relations)) {
+                for (const relation of entry.relations) {
+                    if (!relation || typeof relation !== 'object')
+                        continue;
+                    const type = typeof relation.type === 'string' ? relation.type.trim() : '';
+                    const to = typeof relation.to === 'string' ? relation.to.trim() : '';
+                    if (!type || !to)
+                        continue;
+                    graphRelations.push({
+                        type,
+                        to,
+                    });
+                }
+            }
+            const embeddedAssets = [];
+            const rawEmbeddedAssets = Array.isArray(entry.embeddedAssets)
+                ? entry.embeddedAssets
+                : [];
+            for (let embeddedIndex = 0; embeddedIndex < rawEmbeddedAssets.length; embeddedIndex++) {
+                const embedded = rawEmbeddedAssets[embeddedIndex];
+                const embeddedName = typeof embedded?.name === 'string' ? embedded.name.trim() : '';
+                if (!embeddedName) {
+                    errors.push(`[${label}] Skipping ${rawName}: embeddedAssets[${embeddedIndex}] is missing a name.`);
+                    continue;
+                }
+                const category = normalizeAssetCategoryValue(embedded?.category, errors, `[${label}] Skipping ${rawName}: embedded asset "${embeddedName}"`);
+                if (!category) {
+                    continue;
+                }
+                const subcategory = normalizeAssetSubcategoryValue(embedded?.subcategory, category, errors, `[${label}] Skipping ${rawName}: embedded asset "${embeddedName}"`);
+                if (!subcategory) {
+                    continue;
+                }
+                const fileEntries = embedded?.files && typeof embedded.files === 'object' && !Array.isArray(embedded.files)
+                    ? embedded.files
+                    : null;
+                if (!fileEntries || Object.keys(fileEntries).length === 0) {
+                    errors.push(`[${label}] Skipping ${rawName}: embedded asset "${embeddedName}" must define files.`);
+                    continue;
+                }
+                const files = {};
+                const filePaths = {};
+                let embeddedHasError = false;
+                for (const [role, fileValue] of Object.entries(fileEntries)) {
+                    if (typeof fileValue !== 'string' || !fileValue.trim()) {
+                        errors.push(`[${label}] Skipping ${rawName}: embedded asset "${embeddedName}" file role "${role}" must be a non-empty string path.`);
+                        embeddedHasError = true;
+                        continue;
+                    }
+                    const relativeEmbeddedPath = fileValue.trim();
+                    const absoluteEmbeddedPath = (0, node_path_1.resolve)(file.directory, relativeEmbeddedPath);
+                    if (!(0, node_fs_1.existsSync)(absoluteEmbeddedPath) || !(0, node_fs_1.statSync)(absoluteEmbeddedPath).isFile()) {
+                        errors.push(`[${label}] Skipping ${rawName}: embedded asset "${embeddedName}" file not found at ${absoluteEmbeddedPath}.`);
+                        embeddedHasError = true;
+                        continue;
+                    }
+                    files[role] = relativeEmbeddedPath.replace(/\\/g, '/');
+                    filePaths[role] = absoluteEmbeddedPath;
+                }
+                if (embeddedHasError) {
+                    continue;
+                }
+                if (category === 'SPRITESHEET') {
+                    const hasAtlas = Object.prototype.hasOwnProperty.call(files, 'atlas');
+                    const hasManifest = Object.prototype.hasOwnProperty.call(files, 'manifest');
+                    if (!hasAtlas || !hasManifest) {
+                        errors.push(`[${label}] Skipping ${rawName}: embedded asset "${embeddedName}" with category=SPRITESHEET must define files.atlas and files.manifest.`);
+                        continue;
+                    }
+                }
+                if (category === 'AUDIO') {
+                    const hasPrimary = Object.prototype.hasOwnProperty.call(files, 'primary');
+                    if (!hasPrimary) {
+                        errors.push(`[${label}] Skipping ${rawName}: embedded asset "${embeddedName}" with category=AUDIO must define files.primary.`);
+                        continue;
+                    }
+                }
+                embeddedAssets.push({
+                    kind: 'embedded-asset',
+                    appName: rawName,
+                    name: embeddedName,
+                    cataloguePath: label,
+                    category,
+                    subcategory,
+                    format: typeof embedded?.format === 'string' && embedded.format.trim().length > 0 ? embedded.format.trim().toUpperCase() : undefined,
+                    visibility: normalizeAssetVisibilityValue(embedded?.visibility, errors, `${label} embedded asset \"${embeddedName}\"`),
+                    shopListed: typeof embedded?.shopListed === 'boolean' ? embedded.shopListed : undefined,
+                    shopPriceCoins: Number.isInteger(embedded?.shopPriceCoins) ? Number(embedded.shopPriceCoins) : undefined,
+                    files,
+                    filePaths,
+                });
+            }
+            tasks.push({
+                kind: 'app',
+                name: rawName,
+                cataloguePath: label,
+                catalogueAbsolutePath: file.absolutePath,
+                catalogueDir: file.directory,
+                filePath: absoluteFilePath,
+                relativeFile: fileField.replace(/\\/g, '/'),
+                projectDir: file.directory,
+                packageJsonPath,
+                isTypescriptProject,
+                hasValidateScript,
+                hasFormatScript,
+                displayName: metadata.displayName,
+                description: metadata.description,
+                type: metadata.type,
+                emoji: metadata.emoji === undefined ? undefined : metadata.emoji,
+                color: metadata.color === undefined ? undefined : metadata.color,
+                surfaceTargets: metadata.surfaceTargets,
+                missingMetadata: metadata.missingFields,
+                ecsPath,
+                serverPath,
+                // Versioning fields
+                version,
+                releaseNotes,
+                versionVisibility,
+                hostingMode,
+                externalUrl,
+                listing,
+                // Admin-only field
+                username,
+                embeddedAssets,
+                uses: {
+                    assets: usesAssets,
+                    packs: usesPacks,
+                },
+                graph: {
+                    relations: graphRelations,
+                },
+            });
+        }
+    }
+    return { tasks, warnings, errors };
+}
+function buildAssetTasks(catalogues) {
+    const tasks = [];
+    const warnings = [];
+    const errors = [];
+    const seen = new Map();
+    for (const file of catalogues) {
+        const label = file.relativePath || 'catalogue.json';
+        const rawAssets = Array.isArray(file.data.assets) ? file.data.assets : [];
+        for (let index = 0; index < rawAssets.length; index++) {
+            const entry = rawAssets[index];
+            if (!entry || typeof entry !== 'object') {
+                errors.push(`[${label}] Invalid assets[${index}] entry; expected object.`);
+                continue;
+            }
+            const name = typeof entry.name === 'string' ? entry.name.trim() : '';
+            if (!name) {
+                errors.push(`[${label}] assets[${index}] is missing a name.`);
+                continue;
+            }
+            const hasDisplayName = Object.prototype.hasOwnProperty.call(entry, 'displayName');
+            const displayName = typeof entry.displayName === 'string' ? entry.displayName.trim() : '';
+            if (hasDisplayName && displayName.length === 0) {
+                errors.push(`[${label}] Asset "${name}" displayName must be a non-empty string.`);
+                continue;
+            }
+            const dedupeKey = `${label}::${name}`;
+            if (seen.has(dedupeKey)) {
+                errors.push(`[${label}] Duplicate asset name "${name}" in same catalogue.`);
+                continue;
+            }
+            seen.set(dedupeKey, label);
+            const category = normalizeAssetCategoryValue(entry.category, errors, `[${label}] Asset "${name}"`);
+            if (!category) {
+                continue;
+            }
+            const subcategory = normalizeAssetSubcategoryValue(entry.subcategory, category, errors, `[${label}] Asset "${name}"`);
+            if (!subcategory) {
+                continue;
+            }
+            const fileEntries = entry.files && typeof entry.files === 'object' && !Array.isArray(entry.files)
+                ? entry.files
+                : null;
+            if (!fileEntries || Object.keys(fileEntries).length === 0) {
+                errors.push(`[${label}] Asset "${name}" must define files.`);
+                continue;
+            }
+            const files = {};
+            const filePaths = {};
+            let hasError = false;
+            for (const [role, value] of Object.entries(fileEntries)) {
+                if (typeof value !== 'string' || !value.trim()) {
+                    errors.push(`[${label}] Asset "${name}" file role "${role}" must be a non-empty string path.`);
+                    hasError = true;
+                    continue;
+                }
+                const relativePath = value.trim();
+                const absolutePath = (0, node_path_1.resolve)(file.directory, relativePath);
+                if (!(0, node_fs_1.existsSync)(absolutePath) || !(0, node_fs_1.statSync)(absolutePath).isFile()) {
+                    errors.push(`[${label}] Asset "${name}" file not found at ${absolutePath}.`);
+                    hasError = true;
+                    continue;
+                }
+                files[role] = relativePath.replace(/\\/g, '/');
+                filePaths[role] = absolutePath;
+            }
+            if (hasError) {
+                continue;
+            }
+            if (category === 'SPRITESHEET') {
+                const hasAtlas = Object.prototype.hasOwnProperty.call(files, 'atlas');
+                const hasManifest = Object.prototype.hasOwnProperty.call(files, 'manifest');
+                if (!hasAtlas || !hasManifest) {
+                    errors.push(`[${label}] Asset "${name}" with category=SPRITESHEET must define files.atlas and files.manifest.`);
+                    continue;
+                }
+            }
+            if (category === 'AUDIO') {
+                const hasPrimary = Object.prototype.hasOwnProperty.call(files, 'primary');
+                if (!hasPrimary) {
+                    errors.push(`[${label}] Asset "${name}" with category=AUDIO must define files.primary.`);
+                    continue;
+                }
+            }
+            const relations = Array.isArray(entry.relations)
+                ? entry.relations
+                    .filter((row) => !!row && typeof row === 'object')
+                    .map((row) => ({
+                    type: typeof row.type === 'string' ? row.type : '',
+                    to: typeof row.to === 'string' ? row.to : '',
+                }))
+                    .filter((row) => row.type.trim().length > 0 && row.to.trim().length > 0)
+                : undefined;
+            const username = typeof entry.username === 'string' && entry.username.trim().length > 0
+                ? entry.username.trim()
+                : undefined;
+            tasks.push({
+                kind: 'asset',
+                name,
+                displayName: displayName || undefined,
+                cataloguePath: label,
+                category,
+                subcategory,
+                username,
+                format: typeof entry.format === 'string' && entry.format.trim().length > 0 ? entry.format.trim().toUpperCase() : undefined,
+                visibility: normalizeAssetVisibilityValue(entry.visibility, errors, `${label} asset \"${name}\"`),
+                shopListed: typeof entry.shopListed === 'boolean' ? entry.shopListed : undefined,
+                shopPriceCoins: Number.isInteger(entry.shopPriceCoins) ? Number(entry.shopPriceCoins) : undefined,
+                files,
+                filePaths,
+                relations,
+            });
+        }
+    }
+    return { tasks, warnings, errors };
+}
+function buildAssetPackTasks(catalogues) {
+    const tasks = [];
+    const warnings = [];
+    const errors = [];
+    const seen = new Map();
+    for (const file of catalogues) {
+        const label = file.relativePath || 'catalogue.json';
+        const rawPacks = Array.isArray(file.data.assetPacks) ? file.data.assetPacks : [];
+        for (let index = 0; index < rawPacks.length; index++) {
+            const entry = rawPacks[index];
+            if (!entry || typeof entry !== 'object') {
+                errors.push(`[${label}] Invalid assetPacks[${index}] entry; expected object.`);
+                continue;
+            }
+            const name = typeof entry.name === 'string' ? entry.name.trim() : '';
+            if (!name) {
+                errors.push(`[${label}] assetPacks[${index}] is missing a name.`);
+                continue;
+            }
+            const version = typeof entry.version === 'string' ? entry.version.trim() : '';
+            if (!SEMVER_REGEX.test(version)) {
+                errors.push(`[${label}] Asset pack "${name}" must define a semver version.`);
+                continue;
+            }
+            const dedupeKey = `${label}::${name}::${version}`;
+            if (seen.has(dedupeKey)) {
+                errors.push(`[${label}] Duplicate asset pack "${name}@${version}" in same catalogue.`);
+                continue;
+            }
+            seen.set(dedupeKey, label);
+            const assets = Array.isArray(entry.assets)
+                ? entry.assets.filter((value) => typeof value === 'string' && value.trim().length > 0).map((value) => value.trim())
+                : [];
+            if (assets.length === 0) {
+                errors.push(`[${label}] Asset pack "${name}" must reference at least one asset.`);
+                continue;
+            }
+            const relations = Array.isArray(entry.relations)
+                ? entry.relations
+                    .filter((row) => !!row && typeof row === 'object')
+                    .map((row) => ({
+                    type: typeof row.type === 'string' ? row.type : '',
+                    to: typeof row.to === 'string' ? row.to : '',
+                }))
+                    .filter((row) => row.type.trim().length > 0 && row.to.trim().length > 0)
+                : undefined;
+            const username = typeof entry.username === 'string' && entry.username.trim().length > 0
+                ? entry.username.trim()
+                : undefined;
+            const visibility = typeof entry.visibility === 'string' && entry.visibility.trim().length > 0
+                ? entry.visibility.trim().toUpperCase()
+                : undefined;
+            if (visibility && visibility !== 'PUBLIC' && visibility !== 'PRIVATE') {
+                errors.push(`[${label}] Asset pack "${name}" visibility must be PUBLIC or PRIVATE.`);
+                continue;
+            }
+            let listing;
+            const rawListing = entry.listing;
+            let listingValidationFailed = false;
+            if (rawListing && typeof rawListing === 'object') {
+                const resolvedListing = {
+                    screenshotPortraitPaths: [],
+                    screenshotLandscapePaths: [],
+                    videoPortraitPaths: [],
+                    videoLandscapePaths: [],
+                };
+                if (typeof rawListing.icon === 'string' && rawListing.icon.trim()) {
+                    const validationError = validateListingAssetPath(file.directory, rawListing.icon.trim(), 'assetPacks.listing.icon');
+                    if (validationError) {
+                        errors.push(`[${label}] Skipping asset pack "${name}": ${validationError}`);
+                        listingValidationFailed = true;
+                    }
+                    else {
+                        resolvedListing.iconPath = resolveListingAssetPath(file.directory, rawListing.icon.trim());
+                    }
+                }
+                if (!listingValidationFailed && typeof rawListing.heroPortrait === 'string' && rawListing.heroPortrait.trim()) {
+                    const validationError = validateListingAssetPath(file.directory, rawListing.heroPortrait.trim(), 'assetPacks.listing.heroPortrait');
+                    if (validationError) {
+                        errors.push(`[${label}] Skipping asset pack "${name}": ${validationError}`);
+                        listingValidationFailed = true;
+                    }
+                    else {
+                        resolvedListing.heroPortraitPath = resolveListingAssetPath(file.directory, rawListing.heroPortrait.trim());
+                    }
+                }
+                if (!listingValidationFailed && typeof rawListing.heroLandscape === 'string' && rawListing.heroLandscape.trim()) {
+                    const validationError = validateListingAssetPath(file.directory, rawListing.heroLandscape.trim(), 'assetPacks.listing.heroLandscape');
+                    if (validationError) {
+                        errors.push(`[${label}] Skipping asset pack "${name}": ${validationError}`);
+                        listingValidationFailed = true;
+                    }
+                    else {
+                        resolvedListing.heroLandscapePath = resolveListingAssetPath(file.directory, rawListing.heroLandscape.trim());
+                    }
+                }
+                if (!listingValidationFailed && Array.isArray(rawListing.screenshotsPortrait)) {
+                    for (const p of rawListing.screenshotsPortrait) {
+                        if (typeof p === 'string' && p.trim()) {
+                            const validationError = validateListingAssetPath(file.directory, p.trim(), 'assetPacks.listing.screenshotsPortrait item');
+                            if (validationError) {
+                                errors.push(`[${label}] Skipping asset pack "${name}": ${validationError}`);
+                                listingValidationFailed = true;
+                                break;
+                            }
+                            resolvedListing.screenshotPortraitPaths.push(resolveListingAssetPath(file.directory, p.trim()));
+                        }
+                    }
+                }
+                if (!listingValidationFailed && Array.isArray(rawListing.screenshotsLandscape)) {
+                    for (const p of rawListing.screenshotsLandscape) {
+                        if (typeof p === 'string' && p.trim()) {
+                            const validationError = validateListingAssetPath(file.directory, p.trim(), 'assetPacks.listing.screenshotsLandscape item');
+                            if (validationError) {
+                                errors.push(`[${label}] Skipping asset pack "${name}": ${validationError}`);
+                                listingValidationFailed = true;
+                                break;
+                            }
+                            resolvedListing.screenshotLandscapePaths.push(resolveListingAssetPath(file.directory, p.trim()));
+                        }
+                    }
+                }
+                if (!listingValidationFailed && Array.isArray(rawListing.videosPortrait)) {
+                    for (const p of rawListing.videosPortrait) {
+                        if (typeof p === 'string' && p.trim()) {
+                            const validationError = validateListingAssetPath(file.directory, p.trim(), 'assetPacks.listing.videosPortrait item');
+                            if (validationError) {
+                                errors.push(`[${label}] Skipping asset pack "${name}": ${validationError}`);
+                                listingValidationFailed = true;
+                                break;
+                            }
+                            resolvedListing.videoPortraitPaths.push(resolveListingAssetPath(file.directory, p.trim()));
+                        }
+                    }
+                }
+                if (!listingValidationFailed && Array.isArray(rawListing.videosLandscape)) {
+                    for (const p of rawListing.videosLandscape) {
+                        if (typeof p === 'string' && p.trim()) {
+                            const validationError = validateListingAssetPath(file.directory, p.trim(), 'assetPacks.listing.videosLandscape item');
+                            if (validationError) {
+                                errors.push(`[${label}] Skipping asset pack "${name}": ${validationError}`);
+                                listingValidationFailed = true;
+                                break;
+                            }
+                            resolvedListing.videoLandscapePaths.push(resolveListingAssetPath(file.directory, p.trim()));
+                        }
+                    }
+                }
+                if (listingValidationFailed) {
+                    continue;
+                }
+                listing = resolvedListing;
+            }
+            tasks.push({
+                kind: 'asset-pack',
+                name,
+                version,
+                cataloguePath: label,
+                username,
+                assets,
+                previewApp: typeof entry.previewApp === 'string' && entry.previewApp.trim().length > 0 ? entry.previewApp.trim() : undefined,
+                visibility,
+                releaseNotes: typeof entry.releaseNotes === 'string' ? entry.releaseNotes : undefined,
+                listing,
+                relations,
+            });
+        }
+    }
+    return { tasks, warnings, errors };
+}
+function resolveCatalogueEntries(rootDir, options = {}) {
+    const { files, errors: discoveryErrors } = walkCatalogueTree(rootDir);
+    if (discoveryErrors.length > 0) {
+        return {
+            apps: [],
+            assets: [],
+            embeddedAssets: [],
+            assetPacks: [],
+            warnings: [],
+            errors: discoveryErrors,
+        };
+    }
+    const { tasks: appTasks, warnings: appWarnings, errors: appErrors } = buildAppTasks(rootDir, files, options);
+    const { tasks: assetTasks, warnings: assetWarnings, errors: assetErrors } = buildAssetTasks(files);
+    const { tasks: assetPackTasks, warnings: assetPackWarnings, errors: assetPackErrors } = buildAssetPackTasks(files);
+    const embeddedAssetTasks = appTasks.flatMap((task) => task.embeddedAssets);
+    const warnings = [...appWarnings, ...assetWarnings, ...assetPackWarnings];
+    const errors = [...appErrors, ...assetErrors, ...assetPackErrors];
+    return {
+        apps: appTasks,
+        assets: assetTasks,
+        embeddedAssets: embeddedAssetTasks,
+        assetPacks: assetPackTasks,
+        warnings,
+        errors,
+    };
+}
+function findNearestCatalogue(startDir) {
+    let current = (0, node_path_1.resolve)(startDir);
+    const visited = new Set();
+    while (!visited.has(current)) {
+        visited.add(current);
+        const candidate = (0, node_path_1.join)(current, 'catalogue.json');
+        if ((0, node_fs_1.existsSync)(candidate) && (0, node_fs_1.statSync)(candidate).isFile()) {
+            return candidate;
+        }
+        const parent = (0, node_path_1.dirname)(current);
+        if (parent === current)
+            break;
+        current = parent;
+    }
+    return null;
+}
+function resolveWorkspaceApp(options) {
+    const { cwd, target, appName } = options;
+    if (target) {
+        const absolute = (0, node_path_1.resolve)(cwd, target);
+        if ((0, node_fs_1.existsSync)(absolute)) {
+            const stats = (0, node_fs_1.statSync)(absolute);
+            if (stats.isDirectory()) {
+                const cataloguePath = (0, node_path_1.join)(absolute, 'catalogue.json');
+                if (!(0, node_fs_1.existsSync)(cataloguePath)) {
+                    return {
+                        kind: 'not_found',
+                        reason: 'catalogue_missing',
+                        message: `Directory ${absolute} does not contain catalogue.json.`,
+                    };
+                }
+                return { kind: 'directory', cataloguePath };
+            }
+            if (!stats.isFile() || (0, node_path_1.extname)(absolute).toLowerCase() !== '.html') {
+                return {
+                    kind: 'not_found',
+                    reason: 'app_missing',
+                    message: `Target ${absolute} is not an app HTML file.`,
+                };
+            }
+            return { kind: 'file', htmlPath: absolute };
+        }
+        const lookup = resolveCatalogueEntries(cwd, { filterName: target });
+        if (lookup.errors.length > 0) {
+            return {
+                kind: 'not_found',
+                reason: 'app_missing',
+                message: lookup.errors[0],
+            };
+        }
+        if (lookup.apps.length > 1) {
+            return {
+                kind: 'not_found',
+                reason: 'multiple_apps',
+                message: `Multiple catalogue entries share the app name "${target}".`,
+            };
+        }
+        if (lookup.apps.length === 1) {
+            return { kind: 'app', task: lookup.apps[0], warnings: lookup.warnings };
+        }
+        return {
+            kind: 'not_found',
+            reason: 'app_missing',
+            message: `App "${target}" was not found in any catalogue.json under ${cwd}.`,
+        };
+    }
+    const nearestCatalogue = findNearestCatalogue(cwd);
+    if (!nearestCatalogue) {
+        return {
+            kind: 'not_found',
+            reason: 'catalogue_missing',
+            message: 'Run this command inside a workspace with catalogue.json or provide a path.',
+        };
+    }
+    const catalogueDir = (0, node_path_1.dirname)(nearestCatalogue);
+    const lookup = resolveCatalogueEntries(catalogueDir);
+    if (lookup.errors.length > 0) {
+        return {
+            kind: 'not_found',
+            reason: 'app_missing',
+            message: lookup.errors[0],
+        };
+    }
+    if (lookup.apps.length === 0) {
+        return {
+            kind: 'not_found',
+            reason: 'no_apps',
+            message: `No apps found in ${nearestCatalogue}.`,
+        };
+    }
+    if (appName) {
+        const matched = lookup.apps.find((task) => task.name === appName);
+        if (!matched) {
+            return {
+                kind: 'not_found',
+                reason: 'app_missing',
+                message: `App "${appName}" was not found in ${nearestCatalogue}.`,
+            };
+        }
+        return { kind: 'app', task: matched, warnings: lookup.warnings };
+    }
+    if (lookup.apps.length > 1) {
+        return {
+            kind: 'not_found',
+            reason: 'multiple_apps',
+            message: `Multiple apps found in ${nearestCatalogue}. Specify the app name to continue.`,
+        };
+    }
+    return { kind: 'app', task: lookup.apps[0], warnings: lookup.warnings };
+}
+function formatMetadataWarnings(warnings) {
+    return new Set(warnings);
+}
+function formatMissingMetadataWarnings(task) {
+    if (!task.missingMetadata || task.missingMetadata.length === 0) {
+        return undefined;
+    }
+    return `${task.cataloguePath} (${formatMissingMetadata(task.missingMetadata)})`;
+}
+function findAppTaskByFile(htmlPath) {
+    const normalizedFilePath = normalizePathForComparison(htmlPath);
+    const visited = new Set();
+    let currentDir = (0, node_path_1.dirname)(normalizedFilePath);
+    while (!visited.has(currentDir)) {
+        visited.add(currentDir);
+        const result = resolveCatalogueEntries(currentDir, {
+            filterFile: normalizedFilePath,
+        });
+        if (result.errors.length > 0) {
+            return { errors: result.errors, warnings: [], task: undefined };
+        }
+        if (result.apps.length > 1) {
+            return {
+                errors: [
+                    `Multiple catalogue entries reference ${normalizedFilePath}. Update catalogue.json to make the HTML entry unique.`,
+                ],
+                warnings: [],
+                task: undefined,
+            };
+        }
+        if (result.apps.length === 1) {
+            return { task: result.apps[0], warnings: result.warnings, errors: [] };
+        }
+        const parent = (0, node_path_1.dirname)(currentDir);
+        if (parent === currentDir) {
+            break;
+        }
+        currentDir = parent;
+    }
+    return { task: undefined, warnings: [], errors: [] };
+}