@playcraft/build 0.0.11 → 0.0.14

package/dist/engines/engine-detector.d.ts

@@ -0,0 +1,38 @@
+import type { EngineType } from '../types.js';
+/**
+ * 引擎检测器
+ * 根据项目文件结构自动检测引擎类型
+ */
+export declare class EngineDetector {
+    /**
+     * 检测项目的引擎类型
+     * @param projectDir 项目目录
+     * @returns 引擎类型
+     * @throws 如果无法识别引擎，抛出错误
+     */
+    static detect(projectDir: string): Promise<EngineType>;
+    /**
+     * 检测 PlayCanvas 特有文件
+     */
+    private static detectPlayCanvasFiles;
+    /**
+     * 读取 package.json
+     */
+    private static readPackageJson;
+    /**
+     * 从 package.json 检测引擎类型
+     */
+    private static detectFromPackageJson;
+    /**
+     * 强制指定引擎类型（用于手动指定时验证）
+     */
+    static validateEngine(engine: string): EngineType | null;
+    /**
+     * 获取项目构建命令（从 package.json 的 scripts）
+     */
+    static getBuildCommand(projectDir: string): Promise<string | null>;
+    /**
+     * 检测包管理器（npm/pnpm/yarn）
+     */
+    static detectPackageManager(projectDir: string): Promise<'npm' | 'pnpm' | 'yarn'>;
+}

package/dist/engines/engine-detector.js

@@ -0,0 +1,201 @@
+import fs from 'fs/promises';
+import path from 'path';
+/**
+ * 引擎检测映射表 - 从 package.json 的 dependencies 检测引擎类型
+ * 复用后端 ExternalImportService 的逻辑
+ */
+const ENGINE_DETECTION_MAP = [
+    // PlayCanvas - 优先检测（通过文件名而非 package.json）
+    { match: (n) => n === 'phaser', engine: 'phaser', priority: 100 },
+    { match: (n) => n === 'pixi.js' || n.startsWith('@pixi/'), engine: 'pixijs', priority: 100 },
+    { match: (n) => n === 'three', engine: 'threejs', priority: 100 },
+    { match: (n) => n === 'cocos-creator' || n === 'cc', engine: 'cocos', priority: 100 },
+    { match: (n) => n === 'playcanvas', engine: 'playcanvas', priority: 100 },
+    { match: (n) => n === 'babylonjs' || n.startsWith('@babylonjs/'), engine: 'babylonjs', priority: 100 },
+    { match: (n) => n.startsWith('laya-') || n.startsWith('@layabox/'), engine: 'layaair', priority: 100 },
+    { match: (n) => n === 'egret', engine: 'egret', priority: 100 },
+];
+/**
+ * 引擎检测器
+ * 根据项目文件结构自动检测引擎类型
+ */
+export class EngineDetector {
+    /**
+     * 检测项目的引擎类型
+     * @param projectDir 项目目录
+     * @returns 引擎类型
+     * @throws 如果无法识别引擎，抛出错误
+     */
+    static async detect(projectDir) {
+        // 1. 优先检测 PlayCanvas / PlayCraft 特有文件（最快路径）
+        const isPlayCanvas = await this.detectPlayCanvasFiles(projectDir);
+        if (isPlayCanvas) {
+            return 'playcanvas';
+        }
+        // 2. 检测 package.json
+        const pkg = await this.readPackageJson(projectDir);
+        if (!pkg) {
+            throw new Error(`[EngineDetector] 无法识别项目类型：找不到 package.json 或 PlayCanvas 文件结构\n` +
+                `项目目录: ${projectDir}\n` +
+                `请确保这是一个有效的项目目录。`);
+        }
+        // 3. 从 package.json 检测引擎
+        const engine = this.detectFromPackageJson(pkg);
+        if (engine) {
+            console.log(`[EngineDetector] 检测到引擎: ${engine}（通过 package.json）`);
+            return engine;
+        }
+        // 4. 兜底：generic（任何有 npm build 的项目）
+        console.log('[EngineDetector] 无法识别具体引擎，使用 generic 类型');
+        return 'generic';
+    }
+    /**
+     * 检测 PlayCanvas 特有文件
+     */
+    static async detectPlayCanvasFiles(projectDir) {
+        // 1. 先检查是否是 PlayCraft 项目（manifest.json + format === 'playcraft'）
+        //    PlayCraft 项目也有 manifest.json，但不应被识别为 PlayCanvas Web Build
+        try {
+            const manifestPath = path.join(projectDir, 'manifest.json');
+            await fs.access(manifestPath);
+            const manifestContent = await fs.readFile(manifestPath, 'utf-8');
+            const manifest = JSON.parse(manifestContent);
+            if (manifest.format === 'playcraft' || Array.isArray(manifest.assets)) {
+                // 这是 PlayCraft 格式项目，仍然属于 PlayCanvas 引擎体系
+                console.log('[EngineDetector] 检测到 PlayCraft 项目格式（manifest.json format=playcraft）');
+                return true;
+            }
+        }
+        catch {
+            // manifest.json 不存在或解析失败，继续其他检测
+        }
+        // 2. PlayCanvas Web Build 输出文件（构建产物）
+        //    这些文件是 PlayCanvas 独有的，不会与其他引擎混淆
+        const webBuildIndicators = [
+            'config.json',
+            '__start__.js',
+            '__settings__.js',
+        ];
+        for (const file of webBuildIndicators) {
+            try {
+                await fs.access(path.join(projectDir, file));
+                console.log(`[EngineDetector] 检测到 PlayCanvas Web Build 文件: ${file}`);
+                return true;
+            }
+            catch {
+                // 继续检查下一个
+            }
+        }
+        // 3. PlayCanvas 编辑器导出格式（原始项目数据）
+        //    必须同时存在这些文件才算是 PlayCanvas 编辑器项目
+        const editorExportIndicators = [
+            'assets.json',
+            'scenes.json',
+            'project.json',
+        ];
+        let editorExportCount = 0;
+        for (const file of editorExportIndicators) {
+            try {
+                await fs.access(path.join(projectDir, file));
+                editorExportCount++;
+            }
+            catch {
+                // 继续检查下一个
+            }
+        }
+        // 如果至少有 2 个编辑器导出文件存在，认为是 PlayCanvas 项目
+        if (editorExportCount >= 2) {
+            return true;
+        }
+        return false;
+    }
+    /**
+     * 读取 package.json
+     */
+    static async readPackageJson(projectDir) {
+        try {
+            const pkgPath = path.join(projectDir, 'package.json');
+            const content = await fs.readFile(pkgPath, 'utf-8');
+            return JSON.parse(content);
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * 从 package.json 检测引擎类型
+     */
+    static detectFromPackageJson(pkg) {
+        const allDeps = {
+            ...pkg.dependencies,
+            ...pkg.devDependencies,
+        };
+        // 收集所有匹配的引擎
+        const matches = [];
+        for (const [depName] of Object.entries(allDeps)) {
+            for (const { match, engine, priority } of ENGINE_DETECTION_MAP) {
+                if (match(depName)) {
+                    matches.push({ engine, priority });
+                }
+            }
+        }
+        if (matches.length === 0) {
+            return null;
+        }
+        // 按优先级排序，返回最高优先级的引擎
+        matches.sort((a, b) => b.priority - a.priority);
+        return matches[0].engine;
+    }
+    /**
+     * 强制指定引擎类型（用于手动指定时验证）
+     */
+    static validateEngine(engine) {
+        const validEngines = [
+            'playcanvas', 'phaser', 'pixijs', 'threejs',
+            'cocos', 'babylonjs', 'layaair', 'egret', 'generic'
+        ];
+        if (validEngines.includes(engine)) {
+            return engine;
+        }
+        return null;
+    }
+    /**
+     * 获取项目构建命令（从 package.json 的 scripts）
+     */
+    static async getBuildCommand(projectDir) {
+        const pkg = await this.readPackageJson(projectDir);
+        if (!pkg || !pkg.scripts) {
+            return null;
+        }
+        // 优先查找常见的 build 命令
+        const buildScripts = ['build', 'build:prod', 'build:production', 'dist', 'compile'];
+        for (const script of buildScripts) {
+            if (pkg.scripts[script]) {
+                return script;
+            }
+        }
+        return null;
+    }
+    /**
+     * 检测包管理器（npm/pnpm/yarn）
+     */
+    static async detectPackageManager(projectDir) {
+        // 按优先级检查锁文件
+        const lockFiles = [
+            { file: 'pnpm-lock.yaml', manager: 'pnpm' },
+            { file: 'yarn.lock', manager: 'yarn' },
+            { file: 'package-lock.json', manager: 'npm' },
+        ];
+        for (const { file, manager } of lockFiles) {
+            try {
+                await fs.access(path.join(projectDir, file));
+                return manager;
+            }
+            catch {
+                // 继续检查下一个
+            }
+        }
+        // 默认使用 npm
+        return 'npm';
+    }
+}

package/dist/engines/generic-adapter.d.ts

@@ -0,0 +1,71 @@
+import type { BaseBuildOptions, BaseBuildOutput, EngineType } from '../types.js';
+/**
+ * 通用引擎适配器
+ * 负责外部引擎（Phaser、Three.js、PixiJS 等）的 Base Build
+ * 核心逻辑：npm install + npm run build
+ */
+export declare class GenericAdapter {
+    private projectDir;
+    private options;
+    private engine;
+    constructor(projectDir: string, options: BaseBuildOptions, engine: EngineType);
+    /**
+     * 执行通用基础构建
+     * 流程：
+     * 1. 检测包管理器
+     * 2. 执行 npm install（超时 3 分钟）
+     * 3. 检测 build script
+     * 4. 执行 npm run build（超时 5 分钟）
+     * 5. 查找构建产物目录
+     * 6. 复制构建产物到 outputDir
+     * 7. 写入 .build-metadata.json
+     */
+    baseBuild(): Promise<BaseBuildOutput>;
+    /**
+     * 检测包管理器
+     */
+    private detectPackageManager;
+    /**
+     * 执行 npm install
+     * 超时：3 分钟
+     */
+    private runNpmInstall;
+    /**
+     * 检测 build script
+     */
+    private detectBuildScript;
+    /**
+     * 执行 npm run build
+     * 超时：5 分钟
+     */
+    private runNpmBuild;
+    /**
+     * 查找构建输出目录
+     * 按优先级搜索：dist/、build/、out/、public/
+     */
+    private findBuildOutputDir;
+    /**
+     * 获取嵌套对象值
+     */
+    private getNestedValue;
+    /**
+     * 复制构建产物到输出目录
+     */
+    private copyBuildOutput;
+    /**
+     * 递归复制目录
+     */
+    private copyDirectory;
+    /**
+     * 扫描输出文件
+     */
+    private scanOutputFiles;
+    /**
+     * 保存构建元数据
+     */
+    private saveBuildMetadata;
+    /**
+     * 执行命令并设置超时
+     */
+    private runCommandWithTimeout;
+}

package/dist/engines/generic-adapter.js

@@ -0,0 +1,378 @@
+import fs from 'fs/promises';
+import path from 'path';
+import { spawn } from 'child_process';
+/**
+ * 通用引擎适配器
+ * 负责外部引擎（Phaser、Three.js、PixiJS 等）的 Base Build
+ * 核心逻辑：npm install + npm run build
+ */
+export class GenericAdapter {
+    constructor(projectDir, options, engine) {
+        this.projectDir = projectDir;
+        this.options = options;
+        this.engine = engine;
+        console.log(`[GenericAdapter] 初始化: projectDir=${projectDir}, engine=${engine}`);
+    }
+    /**
+     * 执行通用基础构建
+     * 流程：
+     * 1. 检测包管理器
+     * 2. 执行 npm install（超时 3 分钟）
+     * 3. 检测 build script
+     * 4. 执行 npm run build（超时 5 分钟）
+     * 5. 查找构建产物目录
+     * 6. 复制构建产物到 outputDir
+     * 7. 写入 .build-metadata.json
+     */
+    async baseBuild() {
+        console.log(`[GenericAdapter] 开始构建引擎: ${this.engine}`);
+        // 1. 检测包管理器
+        const packageManager = await this.detectPackageManager();
+        console.log(`[GenericAdapter] 检测到包管理器: ${packageManager}`);
+        // 2. 执行安装
+        console.log('[GenericAdapter] 执行依赖安装...');
+        await this.runNpmInstall(packageManager);
+        // 3. 检测构建命令
+        const buildScript = await this.detectBuildScript();
+        if (!buildScript) {
+            throw new Error(`[GenericAdapter] 未找到 build script\n` +
+                `请确保 package.json 中包含 scripts.build 字段。`);
+        }
+        console.log(`[GenericAdapter] 检测到构建命令: ${buildScript}`);
+        // 4. 执行构建
+        console.log('[GenericAdapter] 执行项目构建...');
+        const originalBuildDir = await this.runNpmBuild(packageManager, buildScript);
+        // 5. 复制构建产物
+        console.log('[GenericAdapter] 复制构建产物...');
+        const files = await this.copyBuildOutput(originalBuildDir);
+        // 6. 构建元数据
+        const metadata = {
+            mode: 'classic', // 外部引擎统一使用 classic 模式
+            engine: this.engine,
+            buildOutputDir: originalBuildDir,
+        };
+        // 7. 保存元数据
+        await this.saveBuildMetadata(metadata);
+        return {
+            outputDir: this.options.outputDir,
+            metadata,
+            files,
+        };
+    }
+    /**
+     * 检测包管理器
+     */
+    async detectPackageManager() {
+        const lockFiles = [
+            { file: 'pnpm-lock.yaml', manager: 'pnpm' },
+            { file: 'yarn.lock', manager: 'yarn' },
+            { file: 'package-lock.json', manager: 'npm' },
+        ];
+        for (const { file, manager } of lockFiles) {
+            try {
+                await fs.access(path.join(this.projectDir, file));
+                return manager;
+            }
+            catch {
+                // 继续检查下一个
+            }
+        }
+        // 默认使用 npm
+        return 'npm';
+    }
+    /**
+     * 执行 npm install
+     * 超时：3 分钟
+     */
+    async runNpmInstall(packageManager) {
+        const cmd = packageManager === 'npm' ? 'npm' : packageManager;
+        const args = ['install'];
+        // npm 使用 --legacy-peer-deps 避免冲突
+        if (packageManager === 'npm') {
+            args.push('--legacy-peer-deps');
+        }
+        console.log(`[GenericAdapter] 运行: ${cmd} ${args.join(' ')}`);
+        await this.runCommandWithTimeout(cmd, args, {
+            cwd: this.projectDir,
+            timeout: 3 * 60 * 1000, // 3 分钟
+            env: {
+                ...process.env,
+                NODE_ENV: 'production',
+                CI: 'true', // 避免交互式提示
+            },
+        });
+        console.log('[GenericAdapter] 依赖安装完成');
+    }
+    /**
+     * 检测 build script
+     */
+    async detectBuildScript() {
+        try {
+            const pkgPath = path.join(this.projectDir, 'package.json');
+            const content = await fs.readFile(pkgPath, 'utf-8');
+            const pkg = JSON.parse(content);
+            if (!pkg.scripts) {
+                return null;
+            }
+            // 优先查找常见的 build 命令
+            const buildScripts = ['build', 'build:prod', 'build:production', 'dist', 'compile'];
+            for (const script of buildScripts) {
+                if (pkg.scripts[script]) {
+                    return script;
+                }
+            }
+            return null;
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * 执行 npm run build
+     * 超时：5 分钟
+     */
+    async runNpmBuild(packageManager, script) {
+        const cmd = packageManager === 'npm' ? 'npm' : packageManager;
+        const args = packageManager === 'npm' ? ['run', script] : [script];
+        console.log(`[GenericAdapter] 运行: ${cmd} ${args.join(' ')}`);
+        await this.runCommandWithTimeout(cmd, args, {
+            cwd: this.projectDir,
+            timeout: 5 * 60 * 1000, // 5 分钟
+            env: {
+                ...process.env,
+                NODE_ENV: 'production',
+                CI: 'true',
+            },
+        });
+        console.log('[GenericAdapter] 项目构建完成');
+        // 查找构建输出目录
+        return this.findBuildOutputDir();
+    }
+    /**
+     * 查找构建输出目录
+     * 按优先级搜索：dist/、build/、out/、public/
+     */
+    async findBuildOutputDir() {
+        const possibleDirs = ['dist', 'build', 'out', 'public'];
+        for (const dir of possibleDirs) {
+            const fullPath = path.join(this.projectDir, dir);
+            try {
+                const stat = await fs.stat(fullPath);
+                if (stat.isDirectory()) {
+                    // 检查目录中是否有 index.html
+                    const files = await fs.readdir(fullPath);
+                    if (files.includes('index.html')) {
+                        console.log(`[GenericAdapter] 找到构建输出目录: ${dir}`);
+                        return fullPath;
+                    }
+                }
+            }
+            catch {
+                // 目录不存在，继续检查下一个
+            }
+        }
+        // 如果没找到，尝试从 package.json 读取
+        try {
+            const pkgPath = path.join(this.projectDir, 'package.json');
+            const content = await fs.readFile(pkgPath, 'utf-8');
+            const pkg = JSON.parse(content);
+            // 常见配置字段
+            const possibleFields = ['build.outDir', 'build.outdir', 'outDir', 'output', 'dist', 'buildDir'];
+            for (const field of possibleFields) {
+                const value = this.getNestedValue(pkg, field);
+                if (value && typeof value === 'string') {
+                    const fullPath = path.join(this.projectDir, value);
+                    try {
+                        const stat = await fs.stat(fullPath);
+                        if (stat.isDirectory()) {
+                            console.log(`[GenericAdapter] 从 package.json 找到构建目录: ${value}`);
+                            return fullPath;
+                        }
+                    }
+                    catch {
+                        // 目录不存在
+                    }
+                }
+            }
+        }
+        catch {
+            // 无法读取 package.json
+        }
+        throw new Error(`[GenericAdapter] 无法找到构建输出目录\n` +
+            `请确保构建输出包含 index.html，且位于以下目录之一：\n` +
+            possibleDirs.join(', '));
+    }
+    /**
+     * 获取嵌套对象值
+     */
+    getNestedValue(obj, path) {
+        return path.split('.').reduce((current, key) => {
+            return current && current[key] !== undefined ? current[key] : undefined;
+        }, obj);
+    }
+    /**
+     * 复制构建产物到输出目录
+     */
+    async copyBuildOutput(buildDir) {
+        const files = {
+            html: '',
+            engine: null,
+            config: '',
+            settings: null,
+            modules: null,
+            start: '',
+            scenes: [],
+            assets: [],
+        };
+        // 验证构建目录
+        const indexPath = path.join(buildDir, 'index.html');
+        try {
+            await fs.access(indexPath);
+        }
+        catch {
+            throw new Error(`[GenericAdapter] 构建输出缺少 index.html\n` +
+                `构建目录: ${buildDir}\n` +
+                `请确保构建脚本生成有效的 HTML 入口文件。`);
+        }
+        // 复制整个构建目录到输出目录
+        await this.copyDirectory(buildDir, this.options.outputDir);
+        // 设置文件路径
+        files.html = path.join(this.options.outputDir, 'index.html');
+        // 扫描其他文件
+        await this.scanOutputFiles(files);
+        console.log(`[GenericAdapter] 构建产物已复制到: ${this.options.outputDir}`);
+        return files;
+    }
+    /**
+     * 递归复制目录
+     */
+    async copyDirectory(src, dest) {
+        // 确保目标目录存在
+        await fs.mkdir(dest, { recursive: true });
+        const entries = await fs.readdir(src, { withFileTypes: true });
+        for (const entry of entries) {
+            const srcPath = path.join(src, entry.name);
+            const destPath = path.join(dest, entry.name);
+            // 安全检查：确保目标路径在输出目录内
+            const resolvedDest = path.resolve(destPath);
+            const resolvedOutput = path.resolve(this.options.outputDir);
+            if (!resolvedDest.startsWith(resolvedOutput)) {
+                console.warn(`[GenericAdapter] 跳过不安全的文件路径: ${srcPath}`);
+                continue;
+            }
+            if (entry.isDirectory()) {
+                await this.copyDirectory(srcPath, destPath);
+            }
+            else {
+                await fs.copyFile(srcPath, destPath);
+            }
+        }
+    }
+    /**
+     * 扫描输出文件
+     */
+    async scanOutputFiles(files) {
+        const scanDir = async (dir, basePath) => {
+            const entries = await fs.readdir(dir, { withFileTypes: true });
+            for (const entry of entries) {
+                const fullPath = path.join(dir, entry.name);
+                const relativePath = path.relative(basePath, fullPath);
+                if (entry.isDirectory()) {
+                    await scanDir(fullPath, basePath);
+                }
+                else {
+                    // 分类文件
+                    const ext = path.extname(entry.name).toLowerCase();
+                    if (['.png', '.jpg', '.jpeg', '.webp', '.gif', '.svg', '.bmp'].includes(ext)) {
+                        files.assets.push(fullPath);
+                    }
+                    else if (['.mp3', '.wav', '.ogg', '.mp4', '.webm'].includes(ext)) {
+                        files.assets.push(fullPath);
+                    }
+                    else if (['.json', '.yaml', '.yml', '.xml'].includes(ext)) {
+                        if (entry.name === 'config.json') {
+                            files.config = fullPath;
+                        }
+                        else {
+                            files.assets.push(fullPath);
+                        }
+                    }
+                }
+            }
+        };
+        try {
+            await scanDir(this.options.outputDir, this.options.outputDir);
+        }
+        catch (error) {
+            console.warn('[GenericAdapter] 扫描输出文件失败:', error);
+        }
+    }
+    /**
+     * 保存构建元数据
+     */
+    async saveBuildMetadata(metadata) {
+        const metadataPath = path.join(this.options.outputDir, '.build-metadata.json');
+        await fs.writeFile(metadataPath, JSON.stringify(metadata, null, 2), 'utf-8');
+        console.log(`[GenericAdapter] 构建元数据已保存（引擎: ${this.engine}）`);
+    }
+    /**
+     * 执行命令并设置超时
+     */
+    runCommandWithTimeout(cmd, args, options) {
+        return new Promise((resolve, reject) => {
+            const controller = new AbortController();
+            const { signal } = controller;
+            const timeoutId = setTimeout(() => {
+                controller.abort();
+                reject(new Error(`[GenericAdapter] 命令超时（${options.timeout / 1000}秒）\n` +
+                    `命令: ${cmd} ${args.join(' ')}\n` +
+                    `请检查项目依赖是否过多，或构建脚本是否有死循环。`));
+            }, options.timeout);
+            const child = spawn(cmd, args, {
+                cwd: options.cwd,
+                env: options.env,
+                stdio: 'pipe',
+                signal,
+            });
+            let stdout = '';
+            let stderr = '';
+            child.stdout?.on('data', (data) => {
+                stdout += data.toString();
+                // 限制输出长度
+                if (stdout.length > 10000) {
+                    stdout = stdout.slice(-5000);
+                }
+            });
+            child.stderr?.on('data', (data) => {
+                stderr += data.toString();
+                // 限制输出长度
+                if (stderr.length > 10000) {
+                    stderr = stderr.slice(-5000);
+                }
+            });
+            child.on('error', (error) => {
+                clearTimeout(timeoutId);
+                if (error.name === 'AbortError') {
+                    reject(new Error(`命令被中止: ${cmd} ${args.join(' ')}`));
+                }
+                else {
+                    reject(new Error(`[GenericAdapter] 命令执行失败\n` +
+                        `命令: ${cmd} ${args.join(' ')}\n` +
+                        `错误: ${error.message}`));
+                }
+            });
+            child.on('close', (code) => {
+                clearTimeout(timeoutId);
+                if (code === 0) {
+                    resolve();
+                }
+                else {
+                    reject(new Error(`[GenericAdapter] 命令退出码非零: ${code}\n` +
+                        `命令: ${cmd} ${args.join(' ')}\n` +
+                        `stdout: ${stdout.slice(-1000)}\n` +
+                        `stderr: ${stderr.slice(-1000)}`));
+                }
+            });
+        });
+    }
+}

package/dist/engines/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * 引擎适配器模块
+ * 支持多引擎构建的基础架构
+ */
+export { EngineDetector } from './engine-detector.js';
+export { PlayCanvasAdapter } from './playcanvas-adapter.js';
+export { GenericAdapter } from './generic-adapter.js';