pixifact-cli 0.6.1 → 0.7.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 youxia
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -82,22 +82,35 @@ bun run build
 
 不要编辑 `.pixifact/generated/**` 下的生成文件。
 
-## 微信小游戏 target
+## Web / 微信 / 抖音统一构建
 
-项目在 `pixifact.project.json` 声明 `targets.wechat` 后，可运行：
+三个平台共享 `src/main.ts` 和 Vite 配置。平台由标准 Vite mode env 文件选择，例如 `.env.wechat`：
+
+```ini
+VITE_PLATFORM=wechat
+VITE_APP_ID=wx123456
+```
+
+微信项目安装 `@pixifact/platform-wechat` 后运行：
 
 ```bash
-pixifact validate --target wechat
-pixifact build --target wechat
-pixifact build --target wechat --mode development
-pixifact dev --target wechat
+pixifact validate --mode wechat
+pixifact build --mode wechat
+pixifact dev --mode wechat
+```
+
+抖音项目安装 `@pixifact/platform-douyin` 后运行：
+
+pixifact validate --mode douyin
+pixifact build --mode douyin
+pixifact dev --mode douyin
 ```
 
-`build` 默认使用 production mode，压缩 `game.js`；development mode 额外输出 source map。`dev` 固定使用 development mode，并在 Scene、脚本、平台配置或资源变化时重建。
+Web mode 只需要 `pixifact`，不安装小游戏平台包也能构建。`dev` 默认 mode 为 `development`，`build` 和 `validate` 默认为 `production`；显式 `--mode` 原样交给 Vite。默认产物目录为 `dist/<platform>/`，需要修改时使用 Vite `build.outDir`。
 
-输出目录由 `targets.wechat.outDir` 决定，可直接导入微信开发者工具。CLI 负责 target 校验、Scene 编译、主包资源 hash、资源分包 / HTTPS 远程资源映射、原生配置复制和 4 MiB 主包 / 20 MiB 总包检查，不负责上传、体验版、审核或发布。
+CLI 使用 Vite 完成 env、TypeScript、tree-shaking、watch、静态资源和产物生命周期；Pixifact 插件负责 Scene 编译、当前平台虚拟模块、Pixi manifest、资源分包、原生配置和包体检查。业务代码只使用 PixiJS `Assets`，不需要手动加载分包。
 
-完整配置和支持矩阵见 [微信小游戏构建](https://github.com/hxg2050/pixifact/blob/main/docs/zh/wechat-minigame.md)，可运行示例见 [wechat-minigame-demo](https://github.com/hxg2050/pixifact/tree/main/sample-projects/wechat-minigame-demo)。
+完整配置见 [微信小游戏构建](https://github.com/hxg2050/pixifact/blob/main/docs/zh/wechat-minigame.md) 和 [抖音小游戏构建](https://github.com/hxg2050/pixifact/blob/main/docs/zh/douyin-minigame.md)，可运行三端示例见 [wechat-minigame-demo](https://github.com/hxg2050/pixifact/tree/main/sample-projects/wechat-minigame-demo)。
 
 ## 环境要求
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pixifact-cli",
-  "version": "0.6.1",
+  "version": "0.7.0",
   "description": "Pixifact Scene 自动化 CLI。",
   "packageManager": "bun@1.3.13",
   "type": "module",
@@ -32,7 +32,7 @@
     "start": "bun src/pixifact-cli.ts"
   },
   "dependencies": {
-    "esbuild": "^0.27.2",
-    "pixifact": "^0.6.1"
+    "pixifact": "^0.7.0",
+    "vite": "^8.0.10"
   }
 }

package/src/automation.ts

@@ -465,7 +465,7 @@ function walkFiles(root: string, directory: string, depth: number, maxDepth: num
 
     for (const entry of entries) {
         const absolute = path.join(directory, entry.name);
-        const relative = path.relative(root, absolute);
+        const relative = toPosixPath(path.relative(root, absolute));
         if (entry.isDirectory()) {
             results.push({
                 path: relative,

package/src/editorServer.ts

@@ -274,7 +274,12 @@ export function watchEditorProject(projectRoot: string, onProjectFileChanged: (p
     const changedPathTimers = new Map<string, ReturnType<typeof setTimeout>>();
     const watcher = fs.watch(projectRoot, { recursive: true }, (_event, fileName) => {
         if (!fileName) return;
-        const changedPath = String(fileName).split(path.sep).join('/');
+        const filePath = String(fileName);
+        const absolutePath = path.resolve(projectRoot, filePath);
+        if (fs.existsSync(absolutePath) && fs.statSync(absolutePath).isDirectory()) {
+            return;
+        }
+        const changedPath = filePath.split(path.sep).join('/');
         const pending = changedPathTimers.get(changedPath);
         if (pending) clearTimeout(pending);
         changedPathTimers.set(changedPath, setTimeout(() => {

package/src/pixifact-cli.ts

@@ -1,6 +1,7 @@
 #!/usr/bin/env bun
 import fs from 'node:fs';
 import path from 'node:path';
+import { pathToFileURL } from 'node:url';
 import { createPixifactAutomation } from './automation';
 import { hintForCommandError } from 'pixifact';
 import { CompileSceneError, compileScenes } from 'pixifact/compiler-node';
@@ -10,19 +11,19 @@ import { captureEditorScreenshot, queryEditorContext } from './editorSession';
 import { queryRuntime, queryRuntimeList } from './runtimeSession';
 import type { RuntimeLogLevel, RuntimeRequest } from 'pixifact/runtime-dev';
 import {
-    buildWechatTarget,
-    devWechatTarget,
-    validateWechatTarget,
-    type WechatDevEvent,
-    WechatTargetError,
-} from './wechatTarget';
+    buildPixifactTarget,
+    devPixifactTarget,
+    validatePixifactTarget,
+    type PixifactDevEvent,
+    PixifactTargetError,
+} from './viteTarget';
 
 type Automation = ReturnType<typeof createPixifactAutomation>;
 
 interface CliOptions {
     automation?: Automation;
     captureEditorScreenshot?: typeof captureEditorScreenshot;
-    onWechatDevEvent?: (event: WechatDevEvent) => void;
+    onDevEvent?: (event: PixifactDevEvent) => void;
     readEditorContext?: typeof queryEditorContext;
     listRuntimes?: typeof queryRuntimeList;
     queryRuntime?: typeof queryRuntime;
@@ -94,6 +95,17 @@ function optionalFlag(flags: Record<string, string | true>, name: string) {
     return value === undefined ? undefined : requireFlag(flags, name);
 }
 
+function assertAllowedFlags(
+    flags: Record<string, string | true>,
+    allowed: readonly string[],
+    command: string,
+) {
+    const unexpected = Object.keys(flags).find((name) => !allowed.includes(name));
+    if (unexpected !== undefined) {
+        throw new Error(`Unknown option "--${unexpected}" for Pixifact ${command}.`);
+    }
+}
+
 function finiteNumberFlag(flags: Record<string, string | true>, name: string) {
     const value = Number(requireFlag(flags, name));
     if (!Number.isFinite(value)) throw new Error(`--${name} must be a finite number.`);
@@ -256,7 +268,7 @@ async function executeFileCommand(
     positionals: string[],
     flags: Record<string, string | true>,
     automation: Automation,
-    onWechatDevEvent?: (event: WechatDevEvent) => void,
+    onDevEvent?: (event: PixifactDevEvent) => void,
     startEditor: typeof startEditorServer = startEditorServer,
     readEditorContext: typeof queryEditorContext = queryEditorContext,
     captureScreenshot: typeof captureEditorScreenshot = captureEditorScreenshot,
@@ -371,68 +383,61 @@ async function executeFileCommand(
     }
 
     if ((area === 'build' || area === 'dev' || area === 'validate') && action === undefined) {
-        const target = requireFlag(flags, 'target');
-        if (target !== 'wechat') {
-            throw new Error(`Unknown Pixifact target "${target}".`);
-        }
+        assertAllowedFlags(flags, ['mode', 'project-root'], area);
+        const mode = flags.mode === undefined
+            ? area === 'dev' ? 'development' : 'production'
+            : requireFlag(flags, 'mode');
         if (area === 'validate') {
-            const result = await validateWechatTarget(projectRoot);
+            const result = await validatePixifactTarget(projectRoot, mode);
             return result.diagnostics.length > 0
                 ? {
                     ok: false,
-                    target,
+                    mode,
+                    platform: result.platform,
                     diagnostics: result.diagnostics,
-                    hint: 'Fix the listed WeChat target diagnostics, then validate again.',
+                    hint: 'Fix the listed target diagnostics, then validate again.',
                 }
-                : { ok: true, projectRoot, target };
+                : { ok: true, projectRoot, mode, platform: result.platform };
         }
         if (area === 'dev') {
-            if (flags.mode !== undefined) {
-                throw new Error('dev --target wechat always uses development mode; remove --mode.');
-            }
             try {
-                const session = await devWechatTarget(projectRoot, onWechatDevEvent);
+                const session = await devPixifactTarget(projectRoot, mode, onDevEvent);
                 return {
                     ok: true,
                     projectRoot,
-                    target,
-                    mode: 'development',
+                    platform: session.platform,
+                    mode,
                     watching: true,
                     report: session.initialReport,
                 };
             } catch (error) {
-                if (error instanceof WechatTargetError) {
+                if (error instanceof PixifactTargetError) {
                     return {
                         ok: false,
-                        target,
                         error: error.message,
                         diagnostics: error.diagnostics,
-                        hint: 'Fix the listed WeChat target diagnostics, then start dev again.',
+                        hint: 'Fix the listed target diagnostics, then start dev again.',
                     };
                 }
                 throw error;
             }
         }
-        const mode = flags.mode === undefined ? 'production' : requireFlag(flags, 'mode');
-        if (mode !== 'development' && mode !== 'production') {
-            throw new Error('--mode must be development or production.');
-        }
         try {
+            const report = await buildPixifactTarget(projectRoot, mode);
             return {
                 ok: true,
                 projectRoot,
-                target,
+                platform: report.platform,
                 mode,
-                report: await buildWechatTarget(projectRoot, mode),
+                report,
             };
         } catch (error) {
-            if (error instanceof WechatTargetError) {
+            if (error instanceof PixifactTargetError) {
                 return {
                     ok: false,
-                    target,
                     error: error.message,
                     diagnostics: error.diagnostics,
-                    hint: 'Fix the listed WeChat target diagnostics, then build again.',
+                    hint: 'Fix the listed target diagnostics, then build again.',
                 };
             }
             throw error;
@@ -510,9 +515,9 @@ export async function executePixifactCli(argv: string[], options: CliOptions = {
                         'scene inspect --scene <scene-path>',
                         'scene validate --scene <scene-path>',
                         'compile-scenes',
-                        'validate --target wechat',
-                        'build --target wechat',
-                        'dev --target wechat',
+                        'validate [--mode <vite-mode>]',
+                        'build [--mode <vite-mode>]',
+                        'dev [--mode <vite-mode>]',
                     ],
                     aiValidationAlternatives: [
                         'scene validate --all',
@@ -550,7 +555,7 @@ export async function executePixifactCli(argv: string[], options: CliOptions = {
             parsed.positionals,
             parsed.flags,
             automation,
-            options.onWechatDevEvent,
+            options.onDevEvent,
             options.startEditor,
             options.readEditorContext,
             options.captureEditorScreenshot,
@@ -582,9 +587,9 @@ export async function executePixifactCli(argv: string[], options: CliOptions = {
     }
 }
 
-if (import.meta.url === `file://${process.argv[1]}`) {
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
     const result = await executePixifactCli(process.argv.slice(2), {
-        onWechatDevEvent: (event) => process.stdout.write(jsonLine(event)),
+        onDevEvent: (event) => process.stdout.write(jsonLine(event)),
     });
     process.stdout.write(result.stdout);
     process.stderr.write(result.stderr);

package/src/viteTarget.ts

@@ -0,0 +1,323 @@
+import { access, readFile, readdir, stat } from 'node:fs/promises';
+import path from 'node:path';
+import {
+    build,
+    createServer,
+    resolveConfig,
+    type Rollup,
+} from 'vite';
+import {
+    parsePixifactProjectConfig,
+    pixifactProjectConfigFileName,
+    type PixifactProjectConfig,
+} from 'pixifact';
+import {
+    compilerSceneNodeLocator,
+    parseSceneTemplate,
+    type SceneTemplateNode,
+} from 'pixifact/compiler';
+import {
+    loadPixifactEnv,
+    pixifactBuildReporter,
+    type PixifactBuildReport,
+    type PixifactPlatform,
+} from 'pixifact/compiler-node';
+
+export interface PixifactTargetDiagnostic {
+    asset?: string;
+    message: string;
+    node?: string;
+    scene?: string;
+}
+
+export type PixifactDevEvent = {
+    type: 'built';
+    report: PixifactBuildReport;
+} | {
+    type: 'error';
+    error: string;
+};
+
+export interface PixifactDevSession {
+    close(): Promise<void>;
+    initialReport: PixifactBuildReport;
+    platform: PixifactPlatform;
+}
+
+export class PixifactTargetError extends Error {
+    constructor(
+        message: string,
+        readonly diagnostics: PixifactTargetDiagnostic[],
+    ) {
+        super(message);
+        this.name = 'PixifactTargetError';
+    }
+}
+
+export async function validatePixifactTarget(projectRootInput: string, mode: string) {
+    const projectRoot = path.resolve(projectRootInput);
+    const { platform } = loadPixifactEnv(projectRoot, mode);
+    const config = parsePixifactProjectConfig(JSON.parse(await readFile(
+        path.join(projectRoot, pixifactProjectConfigFileName),
+        'utf8',
+    )));
+    const diagnostics = await collectDiagnostics(projectRoot, config, platform);
+    const resolved = await resolveConfig({ root: projectRoot, mode, logLevel: 'silent' }, 'build', mode);
+    const pluginNames = new Set(resolved.plugins.map((plugin) => plugin.name));
+    for (const name of [
+        'pixifact-scenes',
+        'pixifact-platform',
+        'pixifact-assets',
+        'pixifact-resources',
+        'pixifact-minigame',
+    ]) {
+        if (!pluginNames.has(name)) {
+            diagnostics.push({ message: `vite.config.ts must include pixifact(); missing ${name}.` });
+            break;
+        }
+    }
+    if (platform !== 'web') {
+        const packageName = `@pixifact/platform-${platform}`;
+        const resolve = resolved.createResolver();
+        if (!await resolve(packageName, path.join(projectRoot, 'src/main.ts'))) {
+            diagnostics.push({
+                message: `缺少 ${packageName}；请运行 bun add ${packageName}。`,
+            });
+        }
+    }
+    return { config, diagnostics, mode, platform, projectRoot, resolved };
+}
+
+export async function buildPixifactTarget(
+    projectRootInput: string,
+    mode: string,
+): Promise<PixifactBuildReport> {
+    const validation = await validatePixifactTarget(projectRootInput, mode);
+    if (validation.diagnostics.length > 0) {
+        throw new PixifactTargetError('Pixifact target validation failed.', validation.diagnostics);
+    }
+    let report: PixifactBuildReport | undefined;
+    await build({
+        root: validation.projectRoot,
+        mode,
+        logLevel: 'silent',
+        plugins: [pixifactBuildReporter(validation.platform, (value) => {
+            report = value;
+        })],
+    });
+    if (!report) throw new Error('Vite completed without a Pixifact build report.');
+    return report;
+}
+
+export async function devPixifactTarget(
+    projectRootInput: string,
+    mode: string,
+    onEvent: (event: PixifactDevEvent) => void = () => undefined,
+): Promise<PixifactDevSession> {
+    const validation = await validatePixifactTarget(projectRootInput, mode);
+    if (validation.diagnostics.length > 0) {
+        throw new PixifactTargetError('Pixifact target validation failed.', validation.diagnostics);
+    }
+    if (validation.platform === 'web') {
+        const server = await createServer({
+            root: validation.projectRoot,
+            mode,
+            logLevel: 'silent',
+        });
+        await server.listen();
+        return {
+            close: () => server.close(),
+            initialReport: emptyReport('web', validation.resolved.build.outDir),
+            platform: 'web',
+        };
+    }
+    let resolveInitial: (report: PixifactBuildReport) => void;
+    let rejectInitial: (error: Error) => void;
+    const initial = new Promise<PixifactBuildReport>((resolve, reject) => {
+        resolveInitial = resolve;
+        rejectInitial = reject;
+    });
+    let first = true;
+    let completedReport: PixifactBuildReport | undefined;
+    const watcher = await build({
+        root: validation.projectRoot,
+        mode,
+        logLevel: 'silent',
+        build: { watch: {} },
+        plugins: [pixifactBuildReporter(validation.platform, (report) => {
+            completedReport = report;
+        })],
+    }) as Rollup.RollupWatcher;
+    watcher.on('event', (event) => {
+        if (event.code === 'END' && completedReport) {
+            const report = completedReport;
+            completedReport = undefined;
+            if (first) {
+                first = false;
+                resolveInitial(report);
+            } else {
+                onEvent({ type: 'built', report });
+            }
+        } else if (event.code === 'ERROR') {
+            const error = event.error instanceof Error ? event.error : new Error(String(event.error));
+            if (first) {
+                first = false;
+                rejectInitial(error);
+            } else {
+                onEvent({ type: 'error', error: error.message });
+            }
+        }
+    });
+    return {
+        close: () => watcher.close(),
+        initialReport: await initial,
+        platform: validation.platform,
+    };
+}
+
+async function collectDiagnostics(
+    projectRoot: string,
+    config: PixifactProjectConfig,
+    platform: PixifactPlatform,
+) {
+    const diagnostics: PixifactTargetDiagnostic[] = [];
+    await requireFile(projectRoot, 'src/main.ts', diagnostics, '应用入口 src/main.ts 不存在。');
+    if (platform !== 'web') {
+        await requireFile(projectRoot, `platforms/${platform}/game.json`, diagnostics, `${platform} game.json 不存在。`);
+        await requireFile(
+            projectRoot,
+            `platforms/${platform}/project.config.json`,
+            diagnostics,
+            `${platform} project.config.json 不存在。`,
+        );
+    }
+    for (const pack of config.resourcePacks ?? []) {
+        const root = path.join(projectRoot, 'resources', pack);
+        if (!await isDirectory(root)) {
+            diagnostics.push({ asset: `resources/${pack}`, message: `资源包 ${pack} 的目录不存在。` });
+            continue;
+        }
+        if (platform !== 'web') {
+            for (const file of await collectFiles(root)) {
+                if (path.extname(file).toLowerCase() === '.svg') {
+                    diagnostics.push({
+                        asset: projectPath(projectRoot, file),
+                        message: `${platform} 小游戏不支持 SVG 资源。`,
+                    });
+                }
+            }
+        }
+    }
+    for (const scene of Object.values(config.scenes)) {
+        if (!await exists(path.join(projectRoot, scene))) {
+            diagnostics.push({ asset: scene, message: 'Scene 文件不存在。' });
+            continue;
+        }
+        if (platform === 'web') continue;
+        const template = parseSceneTemplate(await readFile(path.join(projectRoot, scene), 'utf8'));
+        await collectSceneDiagnostics(template.children, scene, '', projectRoot, platform, diagnostics);
+    }
+    if (platform !== 'web') {
+        const gameJsonPath = path.join(projectRoot, 'platforms', platform, 'game.json');
+        if (await exists(gameJsonPath)) {
+            const gameJson = JSON.parse(await readFile(gameJsonPath, 'utf8')) as Record<string, unknown>;
+            const property = platform === 'wechat' ? 'subpackages' : 'subPackages';
+            if (gameJson[property] !== undefined) {
+                diagnostics.push({
+                    asset: `platforms/${platform}/game.json`,
+                    message: `${property} 由 Pixifact 根据 resourcePacks 生成，不能在源模板中重复声明。`,
+                });
+            }
+        }
+    }
+    return diagnostics;
+}
+
+async function collectSceneDiagnostics(
+    nodes: SceneTemplateNode[],
+    scene: string,
+    parentPath: string,
+    projectRoot: string,
+    platform: Exclude<PixifactPlatform, 'web'>,
+    diagnostics: PixifactTargetDiagnostic[],
+) {
+    for (const [index, node] of nodes.entries()) {
+        const nodePath = parentPath ? `${parentPath}/${index}` : String(index);
+        if (node.kind === 'slotOutlet') continue;
+        if (node.kind === 'sceneInstance') {
+            for (const [slotName, children] of Object.entries(node.slots)) {
+                await collectSceneDiagnostics(children, scene, `${nodePath}/slot:${slotName}`, projectRoot, platform, diagnostics);
+            }
+            continue;
+        }
+        const locator = compilerSceneNodeLocator(node, nodePath);
+        if (node.type === 'HTMLText' || node.type === 'DOMContainer') {
+            diagnostics.push({ message: `${platform} 小游戏不支持 ${node.type}。`, node: locator, scene });
+        }
+        if (typeof node.props.texture === 'string') {
+            const texture = node.props.texture;
+            const extension = path.extname(texture).toLowerCase();
+            if (!isProjectAssetPath(texture)) {
+                diagnostics.push({ asset: texture, message: `${platform} 小游戏 Scene 纹理必须使用项目相对路径。`, node: locator, scene });
+            } else if (!['.jpeg', '.jpg', '.png', '.webp'].includes(extension)) {
+                diagnostics.push({ asset: texture, message: `${platform} 小游戏 Scene 纹理不支持 ${extension || '无扩展名'} 格式。`, node: locator, scene });
+            } else if (!await exists(path.join(projectRoot, texture))) {
+                diagnostics.push({ asset: texture, message: `${platform} 小游戏 Scene 纹理文件不存在。`, node: locator, scene });
+            }
+        }
+        await collectSceneDiagnostics(node.children, scene, nodePath, projectRoot, platform, diagnostics);
+    }
+}
+
+function isProjectAssetPath(value: string) {
+    return value.trim() !== ''
+        && !value.startsWith('/')
+        && !value.startsWith('./')
+        && !value.includes('\\')
+        && !value.split('/').includes('..')
+        && !/^[a-zA-Z][a-zA-Z\d+.-]*:/.test(value);
+}
+
+async function requireFile(
+    projectRoot: string,
+    relativePath: string,
+    diagnostics: PixifactTargetDiagnostic[],
+    message: string,
+) {
+    if (!await exists(path.join(projectRoot, relativePath))) diagnostics.push({ asset: relativePath, message });
+}
+
+async function collectFiles(root: string): Promise<string[]> {
+    const files: string[] = [];
+    for (const entry of await readdir(root, { withFileTypes: true })) {
+        const absolute = path.join(root, entry.name);
+        if (entry.isDirectory()) files.push(...await collectFiles(absolute));
+        else if (entry.isFile()) files.push(absolute);
+    }
+    return files;
+}
+
+async function exists(filePath: string) {
+    try {
+        await access(filePath);
+        return true;
+    } catch {
+        return false;
+    }
+}
+
+async function isDirectory(filePath: string) {
+    try {
+        return (await stat(filePath)).isDirectory();
+    } catch {
+        return false;
+    }
+}
+
+function emptyReport(platform: PixifactPlatform, outputDirectory: string): PixifactBuildReport {
+    return { mainPackageBytes: 0, outputDirectory, platform, subpackages: {}, totalPackageBytes: 0 };
+}
+
+function projectPath(root: string, filePath: string) {
+    return path.relative(root, filePath).replaceAll(path.sep, '/');
+}

package/src/wechatTarget.ts

@@ -1,578 +0,0 @@
-import { createHash } from 'node:crypto';
-import { watch as watchFiles, type FSWatcher } from 'node:fs';
-import { access, cp, mkdir, readFile, readdir, rm, stat, writeFile } from 'node:fs/promises';
-import path from 'node:path';
-import { build, type BuildOptions, type Plugin } from 'esbuild';
-import {
-    parsePixifactProjectConfig,
-    pixifactProjectConfigFileName,
-    type PixifactProjectConfig,
-    type PixifactWechatTargetConfig,
-} from 'pixifact';
-import {
-    compilerSceneNodeLocator,
-    parseSceneTemplate,
-    type SceneTemplateNode,
-} from 'pixifact/compiler';
-import { compileScenes, generatedSceneAssetsFileName } from 'pixifact/compiler-node';
-
-const wechatMainPackageLimit = 4 * 1024 * 1024;
-const wechatTotalPackageLimit = 20 * 1024 * 1024;
-const supportedWechatTextureExtensions = new Set(['.jpeg', '.jpg', '.png', '.webp']);
-
-export interface WechatTargetDiagnostic {
-    asset?: string;
-    message: string;
-    node?: string;
-    scene?: string;
-}
-
-export interface WechatBuildReport {
-    mainPackageBytes: number;
-    outputDirectory: string;
-    subpackages: Record<string, number>;
-    totalPackageBytes: number;
-}
-
-export type WechatDevEvent = {
-    type: 'built';
-    report: WechatBuildReport;
-} | {
-    type: 'error';
-    error: string;
-    diagnostics?: WechatTargetDiagnostic[];
-};
-
-export interface WechatDevSession {
-    close(): void;
-    initialReport: WechatBuildReport;
-}
-
-export class WechatTargetError extends Error {
-    constructor(
-        message: string,
-        readonly diagnostics: WechatTargetDiagnostic[],
-    ) {
-        super(message);
-        this.name = 'WechatTargetError';
-    }
-}
-
-interface WechatTargetContext {
-    config: PixifactProjectConfig;
-    projectRoot: string;
-    target: PixifactWechatTargetConfig;
-}
-
-interface SceneAssetLocation {
-    pack?: string;
-    src: string;
-}
-
-interface SceneAssetReference {
-    asset: string;
-    node: string;
-    scene: string;
-}
-
-export async function validateWechatTarget(projectRootInput: string) {
-    const context = await readTargetContext(projectRootInput);
-    const diagnostics = await collectWechatDiagnostics(context);
-    return { context, diagnostics };
-}
-
-export async function buildWechatTarget(
-    projectRootInput: string,
-    mode: 'development' | 'production',
-): Promise<WechatBuildReport> {
-    const { context, diagnostics } = await validateWechatTarget(projectRootInput);
-    if (diagnostics.length > 0) {
-        throw new WechatTargetError('WeChat target validation failed.', diagnostics);
-    }
-    await compileScenes({ projectRoot: context.projectRoot });
-    const generatedDir = path.join(context.projectRoot, '.pixifact', 'generated');
-    const assets = JSON.parse(
-        await readFile(path.join(generatedDir, generatedSceneAssetsFileName), 'utf8'),
-    ) as string[];
-    const outputDirectory = path.resolve(context.projectRoot, context.target.outDir);
-    assertSafeOutputDirectory(context, outputDirectory);
-    await rm(outputDirectory, { force: true, recursive: true });
-    await mkdir(outputDirectory, { recursive: true });
-
-    const manifest = await emitTargetAssets(context, assets, outputDirectory);
-    await copyWechatConfiguration(context, outputDirectory);
-    await build(wechatBuildOptions(context, outputDirectory, manifest, mode));
-    const report = await createBuildReport(context, outputDirectory);
-    const sizeDiagnostics: WechatTargetDiagnostic[] = [];
-    if (report.mainPackageBytes > wechatMainPackageLimit) {
-        sizeDiagnostics.push({ message: `微信主包为 ${report.mainPackageBytes} bytes，超过 4 MiB 限制。` });
-    }
-    if (report.totalPackageBytes > wechatTotalPackageLimit) {
-        sizeDiagnostics.push({ message: `微信代码包总计 ${report.totalPackageBytes} bytes，超过 20 MiB 限制。` });
-    }
-    if (sizeDiagnostics.length > 0) {
-        throw new WechatTargetError('WeChat package size validation failed.', sizeDiagnostics);
-    }
-    return report;
-}
-
-export async function devWechatTarget(
-    projectRootInput: string,
-    onEvent: (event: WechatDevEvent) => void = () => undefined,
-): Promise<WechatDevSession> {
-    const initialReport = await buildWechatTarget(projectRootInput, 'development');
-    const { context } = await validateWechatTarget(projectRootInput);
-    const ignoredPaths = new Set([
-        '.git',
-        '.pixifact',
-        'node_modules',
-        context.target.outDir,
-    ]);
-    let watcher: FSWatcher;
-    let debounce: ReturnType<typeof setTimeout> | undefined;
-    let building = false;
-    let queued = false;
-    let closed = false;
-
-    const rebuild = async () => {
-        if (closed) {
-            return;
-        }
-        if (building) {
-            queued = true;
-            return;
-        }
-        building = true;
-        try {
-            const report = await buildWechatTarget(context.projectRoot, 'development');
-            ignoredPaths.add(projectPath(context.projectRoot, report.outputDirectory));
-            onEvent({ type: 'built', report });
-        } catch (error) {
-            onEvent(wechatDevErrorEvent(error));
-        } finally {
-            building = false;
-            if (queued) {
-                queued = false;
-                void rebuild();
-            }
-        }
-    };
-    watcher = watchFiles(context.projectRoot, { recursive: true }, (_eventType, filename) => {
-        const relativePath = filename?.toString().replaceAll(path.sep, '/');
-        if (!relativePath || [...ignoredPaths].some((ignored) =>
-            relativePath === ignored || relativePath.startsWith(`${ignored}/`)
-        )) {
-            return;
-        }
-        clearTimeout(debounce);
-        debounce = setTimeout(() => void rebuild(), 80);
-    });
-
-    return {
-        close() {
-            if (closed) {
-                return;
-            }
-            closed = true;
-            clearTimeout(debounce);
-            watcher.close();
-        },
-        initialReport,
-    };
-}
-
-function wechatDevErrorEvent(error: unknown): WechatDevEvent {
-    return error instanceof WechatTargetError
-        ? { type: 'error', error: error.message, diagnostics: error.diagnostics }
-        : { type: 'error', error: error instanceof Error ? error.message : String(error) };
-}
-
-async function readTargetContext(projectRootInput: string): Promise<WechatTargetContext> {
-    const projectRoot = path.resolve(projectRootInput);
-    const config = parsePixifactProjectConfig(JSON.parse(
-        await readFile(path.join(projectRoot, pixifactProjectConfigFileName), 'utf8'),
-    ));
-    const target = config.targets?.wechat;
-    if (!target) {
-        throw new Error('pixifact.project.json does not declare targets.wechat.');
-    }
-    return { config, projectRoot, target };
-}
-
-function assertSafeOutputDirectory(context: WechatTargetContext, outputDirectory: string) {
-    if (outputDirectory === context.projectRoot || !outputDirectory.startsWith(`${context.projectRoot}${path.sep}`)) {
-        throw new Error('targets.wechat.outDir must be a directory inside projectRoot.');
-    }
-    const inputs = [
-        '.pixifact',
-        context.target.entry,
-        context.target.configDir,
-        ...Object.values(context.config.scenes),
-        ...Object.values(context.config.resourcePacks ?? {}).map((pack) => pack.root),
-    ];
-    const outDir = context.target.outDir.replaceAll(path.sep, '/').replace(/\/+$/, '');
-    const containedInput = inputs.find((input) => input === outDir || input.startsWith(`${outDir}/`));
-    if (containedInput) {
-        throw new Error(`targets.wechat.outDir must not contain project input "${containedInput}".`);
-    }
-}
-
-async function collectWechatDiagnostics(context: WechatTargetContext) {
-    const diagnostics: WechatTargetDiagnostic[] = [];
-    const sceneAssets: SceneAssetReference[] = [];
-    await requireFile(context, context.target.entry, diagnostics, '微信入口不存在。');
-    await requireFile(
-        context,
-        path.posix.join(context.target.configDir, 'game.json'),
-        diagnostics,
-        '微信 game.json 不存在。',
-    );
-    await requireFile(
-        context,
-        path.posix.join(context.target.configDir, 'project.config.json'),
-        diagnostics,
-        '微信 project.config.json 不存在。',
-    );
-    for (const [name, pack] of Object.entries(context.config.resourcePacks ?? {})) {
-        if (!context.target.resourcePacks[name]) {
-            diagnostics.push({ message: `微信 target 未声明资源包 ${name} 的 delivery。` });
-        }
-        const root = path.resolve(context.projectRoot, pack.root);
-        if (!await isDirectory(root)) {
-            diagnostics.push({ asset: pack.root, message: `资源包 ${name} 的根目录不存在。` });
-            continue;
-        }
-        for (const file of await collectFiles(root)) {
-            if (path.extname(file).toLowerCase() === '.svg') {
-                diagnostics.push({
-                    asset: projectPath(context.projectRoot, file),
-                    message: '微信小游戏目标不支持 SVG 资源。',
-                });
-            }
-        }
-    }
-    for (const [name, delivery] of Object.entries(context.target.resourcePacks)) {
-        if (delivery.delivery === 'remote' && !isHttpsUrl(delivery.baseUrl)) {
-            diagnostics.push({ message: `远程资源包 ${name} 的 baseUrl 必须使用 HTTPS。` });
-        }
-    }
-    for (const scene of await collectFiles(path.join(context.projectRoot, 'src'), '.scene')) {
-        const scenePath = projectPath(context.projectRoot, scene);
-        const template = parseSceneTemplate(await readFile(scene, 'utf8'));
-        collectSceneDiagnostics(template.children, scenePath, '', diagnostics, sceneAssets);
-    }
-    for (const reference of sceneAssets) {
-        if (!await exists(path.join(context.projectRoot, reference.asset))) {
-            diagnostics.push({
-                ...reference,
-                message: '微信小游戏 Scene 纹理文件不存在。',
-            });
-        }
-    }
-    await validateWechatSubpackages(context, diagnostics);
-    return diagnostics;
-}
-
-function isHttpsUrl(value: string) {
-    try {
-        const url = new URL(value);
-        return url.protocol === 'https:' && url.hostname !== '';
-    } catch {
-        return false;
-    }
-}
-
-function collectSceneDiagnostics(
-    nodes: SceneTemplateNode[],
-    scene: string,
-    parentPath: string,
-    diagnostics: WechatTargetDiagnostic[],
-    assets: SceneAssetReference[],
-) {
-    for (const [index, node] of nodes.entries()) {
-        const nodePath = parentPath ? `${parentPath}/${index}` : String(index);
-        if (node.kind === 'slotOutlet') {
-            continue;
-        }
-        if (node.kind === 'sceneInstance') {
-            for (const [slotName, children] of Object.entries(node.slots)) {
-                collectSceneDiagnostics(children, scene, `${nodePath}/slot:${slotName}`, diagnostics, assets);
-            }
-            continue;
-        }
-        const locator = compilerSceneNodeLocator(node, nodePath);
-        if (node.type === 'HTMLText' || node.type === 'DOMContainer') {
-            diagnostics.push({
-                message: `微信小游戏目标不支持 ${node.type}。`,
-                node: locator,
-                scene,
-            });
-        }
-        if (typeof node.props.texture === 'string') {
-            const texture = node.props.texture;
-            if (!isProjectAssetPath(texture)) {
-                diagnostics.push({
-                    asset: texture,
-                    message: '微信小游戏 Scene 纹理必须使用项目根目录内的相对路径。',
-                    node: locator,
-                    scene,
-                });
-            } else if (!supportedWechatTextureExtensions.has(path.extname(texture).toLowerCase())) {
-                const extension = path.extname(texture).toLowerCase();
-                diagnostics.push({
-                    asset: texture,
-                    message: `微信小游戏 Scene 纹理不支持 ${extension || '无扩展名'} 格式。`,
-                    node: locator,
-                    scene,
-                });
-            } else {
-                assets.push({ asset: texture, node: locator, scene });
-            }
-        }
-        collectSceneDiagnostics(node.children, scene, nodePath, diagnostics, assets);
-    }
-}
-
-function isProjectAssetPath(value: string) {
-    return value.trim() !== ''
-        && !value.startsWith('/')
-        && !value.startsWith('./')
-        && !value.includes('\\')
-        && !value.split('/').includes('..')
-        && !/^[a-zA-Z][a-zA-Z\d+.-]*:/.test(value);
-}
-
-async function validateWechatSubpackages(
-    context: WechatTargetContext,
-    diagnostics: WechatTargetDiagnostic[],
-) {
-    const gameJsonPath = path.join(context.projectRoot, context.target.configDir, 'game.json');
-    if (!await exists(gameJsonPath)) {
-        return;
-    }
-    const gameJson = JSON.parse(await readFile(gameJsonPath, 'utf8')) as {
-        subpackages?: Array<{ name?: string; root?: string }>;
-    };
-    for (const [name, delivery] of Object.entries(context.target.resourcePacks)) {
-        if (delivery.delivery !== 'subpackage') {
-            continue;
-        }
-        const declaration = gameJson.subpackages?.find((subpackage) => subpackage.name === name);
-        if (!declaration || declaration.root !== delivery.root) {
-            diagnostics.push({
-                message: `game.json 必须声明分包 ${name}，root 为 ${delivery.root}。`,
-            });
-        }
-    }
-}
-
-async function emitTargetAssets(
-    context: WechatTargetContext,
-    assets: string[],
-    outputDirectory: string,
-) {
-    const manifest: Record<string, SceneAssetLocation> = {};
-    for (const [name, pack] of Object.entries(context.config.resourcePacks ?? {})) {
-        const delivery = context.target.resourcePacks[name];
-        if (delivery.delivery !== 'subpackage') {
-            continue;
-        }
-        const source = path.join(context.projectRoot, pack.root);
-        const destination = path.join(outputDirectory, delivery.root);
-        await cp(source, destination, { recursive: true });
-        const entry = path.join(destination, 'game.js');
-        if (!await exists(entry)) {
-            await writeFile(entry, '// Pixifact asset-only subpackage.\n');
-        }
-    }
-    for (const asset of assets) {
-        const source = path.resolve(context.projectRoot, asset);
-        const pack = resourcePackFor(context, asset);
-        if (pack) {
-            const sourceRoot = context.config.resourcePacks![pack.name].root;
-            const relative = path.posix.relative(sourceRoot, asset);
-            const delivery = pack.delivery;
-            manifest[asset] = delivery.delivery === 'subpackage'
-                ? { pack: pack.name, src: path.posix.join(delivery.root, relative) }
-                : { src: `${delivery.baseUrl}/${relative}` };
-            continue;
-        }
-        const content = await readFile(source);
-        const extension = path.extname(asset);
-        const basename = path.basename(asset, extension);
-        const hash = createHash('sha256').update(content).digest('hex').slice(0, 8);
-        const output = path.posix.join('assets', `${basename}-${hash}${extension}`);
-        await mkdir(path.dirname(path.join(outputDirectory, output)), { recursive: true });
-        await writeFile(path.join(outputDirectory, output), content);
-        manifest[asset] = { src: output };
-    }
-    return manifest;
-}
-
-function resourcePackFor(context: WechatTargetContext, asset: string) {
-    const matches = Object.entries(context.config.resourcePacks ?? {}).filter(([, pack]) =>
-        asset === pack.root || asset.startsWith(`${pack.root}/`)
-    );
-    if (matches.length > 1) {
-        throw new Error(`Scene asset "${asset}" matches multiple resource packs.`);
-    }
-    const match = matches[0];
-    return match
-        ? { name: match[0], delivery: context.target.resourcePacks[match[0]] }
-        : undefined;
-}
-
-async function copyWechatConfiguration(context: WechatTargetContext, outputDirectory: string) {
-    for (const file of ['game.json', 'project.config.json']) {
-        await cp(
-            path.join(context.projectRoot, context.target.configDir, file),
-            path.join(outputDirectory, file),
-        );
-    }
-}
-
-function wechatBuildOptions(
-    context: WechatTargetContext,
-    outputDirectory: string,
-    manifest: Record<string, SceneAssetLocation>,
-    mode: 'development' | 'production',
-): BuildOptions {
-    return {
-        absWorkingDir: context.projectRoot,
-        assetNames: 'assets/[name]-[hash]',
-        banner: {
-            js: [
-                'var Intl=globalThis.Intl||{};',
-                'var navigator=globalThis.navigator||(globalThis.navigator={gpu:null,userAgent:"WeChatMiniGame"});',
-            ].join('\n'),
-        },
-        bundle: true,
-        define: {
-            'process.env.NODE_ENV': JSON.stringify(mode),
-        },
-        entryPoints: [path.resolve(context.projectRoot, context.target.entry)],
-        format: 'iife',
-        legalComments: 'none',
-        loader: {
-            '.jpeg': 'file',
-            '.jpg': 'file',
-            '.mp3': 'file',
-            '.ogg': 'file',
-            '.png': 'file',
-            '.wav': 'file',
-            '.webp': 'file',
-        },
-        logLevel: 'silent',
-        minify: mode === 'production',
-        outfile: path.join(outputDirectory, 'game.js'),
-        platform: 'browser',
-        plugins: [wechatScenesPlugin(context, manifest)],
-        sourcemap: mode === 'development',
-        target: 'es2020',
-    };
-}
-
-function wechatScenesPlugin(
-    context: WechatTargetContext,
-    manifest: Record<string, SceneAssetLocation>,
-): Plugin {
-    return {
-        name: 'pixifact-wechat-scenes',
-        setup(buildContext) {
-            buildContext.onResolve({ filter: /^pixifact:scenes$/ }, () => ({
-                namespace: 'pixifact-wechat',
-                path: 'scenes',
-            }));
-            buildContext.onLoad({ filter: /^scenes$/, namespace: 'pixifact-wechat' }, () => ({
-                contents: [
-                    "import { configureSceneAssets } from 'pixifact/scene';",
-                    "import { loadWechatSubpackage } from 'pixifact/platform/wechat';",
-                    `import ${JSON.stringify(path.join(context.projectRoot, '.pixifact', 'generated', 'scenes.generated.ts'))};`,
-                    `configureSceneAssets(${JSON.stringify(manifest)}, { loadPack: loadWechatSubpackage });`,
-                ].join('\n'),
-                loader: 'ts',
-                resolveDir: context.projectRoot,
-            }));
-        },
-    };
-}
-
-async function createBuildReport(
-    context: WechatTargetContext,
-    outputDirectory: string,
-): Promise<WechatBuildReport> {
-    const subpackageRoots = Object.fromEntries(
-        Object.entries(context.target.resourcePacks)
-            .filter(([, delivery]) => delivery.delivery === 'subpackage')
-            .map(([name, delivery]) => [name, delivery.delivery === 'subpackage' ? delivery.root : '']),
-    );
-    const subpackages = Object.fromEntries(Object.keys(subpackageRoots).map((name) => [name, 0]));
-    let mainPackageBytes = 0;
-    let totalPackageBytes = 0;
-    const files = await collectFiles(outputDirectory);
-    for (const file of files) {
-        if (file.endsWith('.map') || file.endsWith('project.config.json')) {
-            continue;
-        }
-        const bytes = (await stat(file)).size;
-        const relative = projectPath(outputDirectory, file);
-        const subpackage = Object.entries(subpackageRoots).find(([, root]) =>
-            relative === root || relative.startsWith(`${root}/`)
-        );
-        if (subpackage) {
-            subpackages[subpackage[0]] += bytes;
-        } else {
-            mainPackageBytes += bytes;
-        }
-        totalPackageBytes += bytes;
-    }
-    return { mainPackageBytes, outputDirectory, subpackages, totalPackageBytes };
-}
-
-async function requireFile(
-    context: WechatTargetContext,
-    relativePath: string,
-    diagnostics: WechatTargetDiagnostic[],
-    message: string,
-) {
-    if (!await exists(path.join(context.projectRoot, relativePath))) {
-        diagnostics.push({ asset: relativePath, message });
-    }
-}
-
-async function collectFiles(root: string, suffix?: string) {
-    const files: string[] = [];
-    if (!await isDirectory(root)) {
-        return files;
-    }
-    for (const entry of await readdir(root, { withFileTypes: true })) {
-        const absolute = path.join(root, entry.name);
-        if (entry.isDirectory()) {
-            files.push(...await collectFiles(absolute, suffix));
-        } else if (entry.isFile() && (!suffix || entry.name.endsWith(suffix))) {
-            files.push(absolute);
-        }
-    }
-    return files;
-}
-
-async function exists(filePath: string) {
-    try {
-        await access(filePath);
-        return true;
-    } catch {
-        return false;
-    }
-}
-
-async function isDirectory(filePath: string) {
-    try {
-        return (await stat(filePath)).isDirectory();
-    } catch {
-        return false;
-    }
-}
-
-function projectPath(root: string, filePath: string) {
-    return path.relative(root, filePath).replaceAll(path.sep, '/');
-}