@ttmg/cli 0.3.9 → 0.4.0

package/CHANGELOG.md

@@ -238,4 +238,9 @@ API 预检建议文案统一收敛，避免重复提示，阅读更清晰
 6. 新版本提示由红点改为「有更新」文字标签，含义更直观。
 7. 上传游戏包按钮配色与产品主题色统一。
 8. 修复多个页面中标题与正文内容未对齐的问题，整体排版更整齐。
-9. 文案细节调整：「身份与授权」更名为「登录与授权」；移除侧边栏冗余的「查看文档」入口。
+9. 文案细节调整：「身份与授权」更名为「登录与授权」；移除侧边栏冗余的「查看文档」入口。
+
+## 0.3.9-beta.1
+本次测试版本主要补充启动模式场景能力，并优化场景命名可理解性：
+
+1. 启动模式新增 `inbox` 场景，支持在调试链路中模拟消息入口启动小游戏。

package/dist/index.js

@@ -8372,8 +8372,81 @@ async function compile(context) {
 }
 
 // import { uploadGame } from './uploadGame';
+/* ---------------------------------------------------------------------------
+ * Watch suspension control
+ *
+ * The wasm-split pipeline (prepare / split download / rollback) intentionally
+ * rewrites a burst of project files — the instrumented wasm, the `wasmcode*`
+ * subpackage dirs, `game.json`, `webgl-wasm-split.js`. Without gating, every
+ * one of those writes trips the watcher below, and each trip runs a full
+ * `compile` + device `resourceChange` reload *in the middle of the pipeline*.
+ * That both wastes cycles and can reload the device onto a half-written /
+ * transient build. We suspend the watcher around those operations and fire
+ * exactly one update after they complete ("完成之后再触发更新").
+ *
+ * `suspendDepth` is a refcount so overlapping / nested operations are safe.
+ * `muteUntil` keeps swallowing events for a short cooldown AFTER resume:
+ * chokidar's `awaitWriteFinish` delays events ~1s past the actual write, so
+ * those late events from our own writes would otherwise land after we've
+ * resumed and re-trigger the very reload we just suppressed.
+ * ------------------------------------------------------------------------- */
+let suspendDepth = 0;
+let muteUntil = 0;
+let pendingWhileSuspended = false;
+// chokidar awaitWriteFinish stabilityThreshold (1000ms) + headroom, so the
+// delayed FS events caused by the pipeline's own writes are swallowed.
+const RESUME_COOLDOWN_MS = 2500;
+// Wired up inside `watch()` so suspend/resume can reuse the exact same
+// (debounced) compile + resourceChange action the watcher fires normally.
+let triggerUpdate = null;
+function suspendWatch() {
+    suspendDepth += 1;
+}
+function resumeWatch(options = {}) {
+    if (suspendDepth > 0) {
+        suspendDepth -= 1;
+    }
+    if (suspendDepth > 0) {
+        return;
+    }
+    // Back to depth 0 — start the cooldown that swallows our own delayed FS
+    // events, then emit a single update if anything changed while suspended
+    // (or the caller forces it).
+    muteUntil = Date.now() + RESUME_COOLDOWN_MS;
+    const shouldEmit = options.emit ?? pendingWhileSuspended;
+    pendingWhileSuspended = false;
+    if (shouldEmit) {
+        triggerUpdate?.();
+    }
+}
+/**
+ * Run a project-file-mutating operation with the watcher muted, then fire a
+ * single update once it finishes. Use this around the wasm-split pipeline
+ * steps so their intermediate writes don't each reload the device.
+ */
+async function withWatchSuspended(fn, options = {}) {
+    suspendWatch();
+    try {
+        return await fn();
+    }
+    finally {
+        resumeWatch({ emit: options.emitOnFinish ?? true });
+    }
+}
 async function watch() {
     let debounceTimer = null;
+    const runUpdate = async () => {
+        await compile({ mode: 'watch' });
+        wsServer.sendResourceChange();
+    };
+    triggerUpdate = () => {
+        if (debounceTimer)
+            clearTimeout(debounceTimer);
+        debounceTimer = setTimeout(() => {
+            runUpdate();
+            debounceTimer = null;
+        }, 2000);
+    };
     // 监听当前工作目录，排除 node_modules 和 .git
     const watcher = chokidar.watch(process.cwd(), {
         /**
@@ -8388,17 +8461,20 @@ async function watch() {
     });
     // 任意文件变化都触发
     watcher.on('all', (event, path) => {
-        // 清除之前的定时器
-        if (debounceTimer)
-            clearTimeout(debounceTimer);
-        // 重新设置定时器
-        debounceTimer = setTimeout(async () => {
-            (await compile({
-                mode: 'watch',
-            }),
-                wsServer.sendResourceChange());
-            debounceTimer = null;
-        }, 2000);
+        // Pipeline is actively rewriting project files. Remember that something
+        // changed so the resume flush can fire one update, and skip the per-write
+        // compile/reload.
+        if (suspendDepth > 0) {
+            pendingWhileSuspended = true;
+            return;
+        }
+        // Cooldown window right after a pipeline finished: these are the delayed
+        // `awaitWriteFinish` events from the pipeline's own writes. We already
+        // emitted one update on resume, so swallow them to avoid a double reload.
+        if (Date.now() < muteUntil) {
+            return;
+        }
+        triggerUpdate?.();
     });
     watcher.on('error', error => {
         // console.error(chalk.red('[watch] 监听发生错误:'), error);
@@ -10490,42 +10566,83 @@ function restoreSplitConfigFromCache(entryDir = process.cwd()) {
  * to change.
  */
 function restoreFromCache(entryDir = process.cwd()) {
+    // Rollback rewrites a burst of project files (restored wasm, game.json,
+    // split config, removed split-output dirs). Mute the dev-server watcher for
+    // the duration so it doesn't fire a compile + device reload per file, then
+    // emit a single update once the project is back to its restored state.
+    suspendWatch();
+    try {
+        restoreFromCacheInner(entryDir);
+    }
+    finally {
+        resumeWatch({ emit: true });
+    }
+}
+function restoreFromCacheInner(entryDir) {
     const cacheDir = path.join(entryDir, WASM_SPLIT_CACHE_DIR);
-    // 1) Wipe stale split residue inside wasmcode/ first, THEN restore the
-    //    original. Order matters: if we restore first then wipe, we'd delete
-    //    the very file we just brought back.
     const originDir = path.join(entryDir, WASM_SPLIT_SUBPACKAGE_CONFIG.origin.root);
-    if (fs.existsSync(originDir)) {
-        for (const entry of fs.readdirSync(originDir)) {
-            // Only clean files split is known to write — `.br` (main wasm) and
-            // the empty `game.js` placeholder. Touching anything else risks
-            // nuking developer-authored content that happens to live in
-            // wasmcode/ for unrelated reasons.
-            if (entry.endsWith('.br') || entry === 'game.js') {
-                fs.rmSync(path.join(originDir, entry), { force: true });
+    // Resolve the cached original wasm BEFORE touching anything on disk. The
+    // previous order (wipe `wasmcode/*.br` first, then look for a cached
+    // original to restore) was destructive when the cache had no original to
+    // give back — e.g. the project was duplicated without `__TTMG_TEMP__`, the
+    // temp dir was cleared, or split completed in a session whose cache is gone.
+    // In that case it deleted the project's only wasm and restored nothing,
+    // leaving `wasmcode/` empty while `game.json` still pointed at the now-missing
+    // `<md5>.wasm.br`. The next prepare then crashed the dev server on an ENOENT
+    // decompress. We only clean + restore when we have a confirmed replacement.
+    const cachedWasmBr = fs.existsSync(cacheDir)
+        ? fs.readdirSync(cacheDir).find(item => item.endsWith('.br'))
+        : undefined;
+    if (cachedWasmBr) {
+        // Safe to wipe split residue first: we have a confirmed original to put
+        // back. Order matters — restoring first then wiping would delete the file
+        // we just brought back.
+        if (fs.existsSync(originDir)) {
+            for (const entry of fs.readdirSync(originDir)) {
+                // Only clean files split is known to write — `.br` (main wasm) and
+                // the empty `game.js` placeholder. Touching anything else risks
+                // nuking developer-authored content that happens to live in
+                // wasmcode/ for unrelated reasons.
+                if (entry.endsWith('.br') || entry === 'game.js') {
+                    fs.rmSync(path.join(originDir, entry), { force: true });
+                }
             }
         }
+        const destWasmBrPath = path.join(originDir, path.basename(cachedWasmBr));
+        ensureDirSync(path.dirname(destWasmBrPath));
+        fs.copyFileSync(path.join(cacheDir, cachedWasmBr), destWasmBrPath);
     }
-    if (fs.existsSync(cacheDir)) {
-        const targetWasmBrPath = fs
-            .readdirSync(cacheDir)
-            .find(item => item.endsWith('.br'));
-        if (targetWasmBrPath) {
-            const destWasmBrPath = path.join(entryDir, WASM_SPLIT_SUBPACKAGE_CONFIG.origin.root, path.basename(targetWasmBrPath));
-            ensureDirSync(path.dirname(destWasmBrPath));
-            fs.copyFileSync(path.join(cacheDir, targetWasmBrPath), destWasmBrPath);
-        }
-    }
-    const splitConfigCachePath = path.join(cacheDir, WASM_SPLIT_CONFIG_FILE_NAME);
-    if (fs.existsSync(splitConfigCachePath)) {
-        fs.copyFileSync(splitConfigCachePath, path.join(entryDir, WASM_SPLIT_CONFIG_FILE_NAME));
-    }
-    const gameJsonCachePath = path.join(cacheDir, 'game.json');
-    if (fs.existsSync(gameJsonCachePath)) {
-        fs.copyFileSync(gameJsonCachePath, path.join(entryDir, 'game.json'));
-    }
-    // Restore wasmcode/game.js. We just deleted whatever was there in step 1,
-    // so we always need to put something back when wasmcode is a subpackage.
+    else {
+        // No cached original. Do NOT delete whatever wasm is currently on disk —
+        // it is all the project has left. Preserve it so the project can still
+        // boot and a fresh prepare can re-seed the cache, rather than wiping it and
+        // crashing the next prepare. The split-output dirs below are still cleaned.
+        console.warn('[wasmtool] restoreFromCache: no cached original wasm found in ' +
+            `${WASM_SPLIT_CACHE_DIR}; skipping wasmcode/*.br cleanup to avoid ` +
+            'leaving the project without a wasm binary.');
+    }
+    // Only roll back the split config + game.json when we actually restored the
+    // original wasm above. Restoring game.json (which points at the original
+    // `<md5>.wasm.br`) while the matching wasm is NOT on disk recreates exactly
+    // the broken state this guard exists to prevent — a game.json referencing a
+    // file that isn't there. keepCacheSync writes the wasm, config and game.json
+    // together, so a cache that has game.json but no `.br` is partial/corrupt and
+    // must not be applied.
+    if (cachedWasmBr) {
+        const splitConfigCachePath = path.join(cacheDir, WASM_SPLIT_CONFIG_FILE_NAME);
+        if (fs.existsSync(splitConfigCachePath)) {
+            fs.copyFileSync(splitConfigCachePath, path.join(entryDir, WASM_SPLIT_CONFIG_FILE_NAME));
+        }
+        const gameJsonCachePath = path.join(cacheDir, 'game.json');
+        if (fs.existsSync(gameJsonCachePath)) {
+            fs.copyFileSync(gameJsonCachePath, path.join(entryDir, 'game.json'));
+        }
+    }
+    // Restore wasmcode/game.js. We just deleted whatever was there in the
+    // cleanup loop above, so we always need to put something back when wasmcode
+    // is a subpackage. Scoped to the same `cachedWasmBr` guard: in the degraded
+    // (lost-cache) path we left the existing wasmcode/ untouched, so we must not
+    // rewrite its game.js either.
     // Strategy:
     //   - Prefer the cache (keepCacheSync stashes pre-split contents to
     //     `__unity_cache__/wasmcode-game.js` when the original existed)
@@ -10536,14 +10653,16 @@ function restoreFromCache(entryDir = process.cwd()) {
     //     downloadSplited.ts also writes; it satisfies the platform requirement
     //     without changing semantics for projects that don't use wasmcode as
     //     a subpackage (the file is harmless empty).
-    const originGameJsCachePath = path.join(cacheDir, 'wasmcode-game.js');
-    const originGameJsDestPath = path.join(originDir, 'game.js');
-    if (fs.existsSync(originDir)) {
-        if (fs.existsSync(originGameJsCachePath)) {
-            fs.copyFileSync(originGameJsCachePath, originGameJsDestPath);
-        }
-        else {
-            fs.writeFileSync(originGameJsDestPath, '', 'utf-8');
+    if (cachedWasmBr) {
+        const originGameJsCachePath = path.join(cacheDir, 'wasmcode-game.js');
+        const originGameJsDestPath = path.join(originDir, 'game.js');
+        if (fs.existsSync(originDir)) {
+            if (fs.existsSync(originGameJsCachePath)) {
+                fs.copyFileSync(originGameJsCachePath, originGameJsDestPath);
+            }
+            else {
+                fs.writeFileSync(originGameJsDestPath, '', 'utf-8');
+            }
         }
     }
     for (const subDir of SPLIT_OUTPUT_DIRS) {
@@ -10661,19 +10780,51 @@ function setLocalState(partial) {
     Object.assign(state, partial);
 }
 
+/**
+ * Prepare overwrites the project wasm in place with the instrumented build.
+ * Mute the dev-server file watcher for the duration so the in-place rewrite
+ * doesn't fire a compile + device reload while the file is still being
+ * written, then emit a single update once the instrumented wasm is on disk.
+ */
 async function startPrepare$1(params) {
+    return withWatchSuspended(() => startPrepareImpl(params), {
+        emitOnFinish: true,
+    });
+}
+async function startPrepareImpl(params) {
     const tempDir = path$1.join(process.cwd(), TTMG_TEMP_DIR);
     ensureDirSync(tempDir);
     const inputPath = path$1.join(process.cwd(), params.wasm_file_path);
-    let rawWasmPath = path$1.join(tempDir, 'original.wasm');
-    if (inputPath.endsWith('.br')) {
-        await decompressWasmFile(inputPath, rawWasmPath);
-    }
-    else {
-        fs$1.copyFileSync(inputPath, rawWasmPath);
-    }
+    const rawWasmPath = path$1.join(tempDir, 'original.wasm');
     const preparedWasmPath = path$1.join(tempDir, 'prepared.wasm');
     try {
+        // The project wasm referenced by game.json can legitimately be missing on
+        // disk: a previous rollback may have wiped `wasmcode/*.br` without a cached
+        // original to restore, the project may have been duplicated without
+        // `__TTMG_TEMP__`, or Unity was re-exported. Detect it up front and return
+        // a structured error. Previously the `decompressWasmFile` / `copyFileSync`
+        // below sat OUTSIDE this try block, so a missing input threw ENOENT out of
+        // the route handler as an unhandled rejection and crashed the whole
+        // dev-server process instead of surfacing a recoverable error to the IDE.
+        if (!fs$1.existsSync(inputPath)) {
+            return {
+                data: null,
+                error: {
+                    code: 404,
+                    message: `WASM file not found: ${params.wasm_file_path}. ` +
+                        'The original wasm is missing — a previous "放弃分包" may have removed it ' +
+                        'without a cached original to restore. Re-export the Unity build (or restore ' +
+                        'the original wasm) and try preparing again.',
+                },
+                ctx: { logid: 'local', httpStatusCode: 404 },
+            };
+        }
+        if (inputPath.endsWith('.br')) {
+            await decompressWasmFile(inputPath, rawWasmPath);
+        }
+        else {
+            fs$1.copyFileSync(inputPath, rawWasmPath);
+        }
         const result = ttmgWasmtool.prepare(rawWasmPath, preparedWasmPath);
         verboseLog(`[wasmtool] prepare done: ${result.outputSize} bytes, ${result.timeCost}s`);
         const gameJson = getGameJson();
@@ -11244,7 +11395,18 @@ function updateSubpackageConfigSync(archive = false) {
     fs__namespace.writeFileSync(gameJsonPath, JSON.stringify(gameJson, null, JSON_INDENT) + JSON_EOL);
 }
 
-async function downloadSplited$1(_context) {
+/**
+ * Lays down the split outputs (`wasmcode*` dirs, game.json, webgl-wasm-split.js)
+ * into the project root — a burst of file writes. Mute the watcher across the
+ * whole operation so it doesn't reload the device per file mid-write, then fire
+ * one update once the split layout is fully on disk.
+ */
+async function downloadSplited$1(context) {
+    return withWatchSuspended(() => downloadSplitedImpl(context), {
+        emitOnFinish: true,
+    });
+}
+async function downloadSplitedImpl(_context) {
     const cwd = process.cwd();
     const { splitMeta } = getLocalState();
     if (!splitMeta) {
@@ -11567,7 +11729,17 @@ async function downloadOne(opts) {
     // so the subpackage loader doesn't complain about missing js entries.
     fs.writeFileSync(path.join(path.dirname(out), 'game.js'), '', 'utf-8');
 }
+/**
+ * Remote-mode counterpart of `downloadSplited`: downloads the server-built
+ * split artifacts and copies them into the project root. Same watcher gating
+ * rationale — mute across the burst of writes, emit one update at the end.
+ */
 async function downloadSplitedRemote(context) {
+    return withWatchSuspended(() => downloadSplitedRemoteImpl(context), {
+        emitOnFinish: true,
+    });
+}
+async function downloadSplitedRemoteImpl(context) {
     const cwd = process.cwd();
     const splitTempDir = path.join(cwd, WASM_SPLIT_CACHE_DIR, DIR_SPLIT);
     ensureDirSync(splitTempDir);
@@ -12687,14 +12859,61 @@ const routes = [
     gamePipelineModeGetRoute,
     gameLanguageRoute,
 ];
+/**
+ * Express 4 does not catch rejections from async route handlers — an
+ * unhandled rejection in any handler propagates to the process and, under
+ * Node's default `unhandledRejection` behavior, kills the whole dev server.
+ * That's how a single missing-file ENOENT in `wasm-prepare` could take the
+ * CLI down. Wrap every handler so a failing request returns a 500 instead of
+ * crashing the process. Individual routes can still return structured errors;
+ * this is only the last-resort net for unexpected throws.
+ */
+function withErrorBoundary(handler) {
+    return (req, res, next) => {
+        try {
+            const result = handler(req, res, next);
+            if (result && typeof result.then === 'function') {
+                result.catch((err) => {
+                    console.error(`[dev-server] unhandled error in ${req.method} ${req.path}:`, err);
+                    if (!res.headersSent) {
+                        res
+                            .status(500)
+                            .send({
+                            code: -1,
+                            error: {
+                                code: 500,
+                                message: err instanceof Error ? err.message : String(err),
+                            },
+                        });
+                    }
+                });
+            }
+        }
+        catch (err) {
+            console.error(`[dev-server] unhandled error in ${req.method} ${req.path}:`, err);
+            if (!res.headersSent) {
+                res
+                    .status(500)
+                    .send({
+                    code: -1,
+                    error: {
+                        code: 500,
+                        message: err instanceof Error ? err.message : String(err),
+                    },
+                });
+            }
+        }
+    };
+}
 function registerRoutes(app, options) {
     const allRoutes = [...routes, getGameFallbackRoute(options.publicPath)];
     for (const route of allRoutes) {
+        const handler = withErrorBoundary(route.handler);
         if (route.method === 'get') {
-            app.get(route.path, route.handler);
+            app.get(route.path, handler);
         }
         else if (route.method === 'post') {
-            app.post(route.path, route.handler);
+            app.post(route.path, handler);
         }
     }
 }
@@ -13139,7 +13358,7 @@ async function upload({ clientKey, note = '--', dir, }) {
     }
 }
 
-var version = "0.3.9";
+var version = "0.4.0";
 var pkg = {
 	version: version};