@dimina-kit/devkit 0.1.2-dev.20260612025610 → 0.1.2-dev.20260612152115

package/dist/index.d.ts

@@ -1,3 +1,9 @@
+import type { CompileLogEntry } from './compile-worker.js';
+export { createRebuildScheduler } from './rebuild-scheduler.js';
+export type { RebuildScheduler } from './rebuild-scheduler.js';
+export { filterDmccLogLine } from './compile-log.js';
+export { createCompileWorker } from './compile-worker.js';
+export type { CompileLogEntry, CompileWorker } from './compile-worker.js';
 export interface AppInfo {
     appId: string;
     name: string;
@@ -19,14 +25,22 @@ export interface OpenProjectOptions {
     watch?: boolean;
     onRebuild?: () => void;
     onBuildError?: (err: unknown) => void;
+    /**
+     * Per-line dmcc compile log, already filtered through `filterDmccLogLine`
+     * (noise stripped, signal kept). Lines come from the forked compile
+     * worker's piped stdout/stderr, tagged with their source stream.
+     */
+    onLog?: (entry: CompileLogEntry) => void;
 }
 export declare function openProject(opts: OpenProjectOptions): Promise<ProjectSession>;
 /**
  * Watch a project directory and invoke `onChange` whenever a source file is
  * created, modified, or deleted. Returns a handle whose `close()` stops the
- * watcher.
+ * watcher and whose `ready` resolves once the initial scan is complete (only
+ * changes made after that point are guaranteed to surface).
  */
 export declare function createProjectWatcher(projectPath: string, onChange: () => void | Promise<void>): {
     close: () => Promise<void>;
+    ready: Promise<void>;
 };
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAiDA,MAAM,WAAW,OAAO;IACvB,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,CAAA;CACZ;AAED,MAAM,WAAW,cAAc;IAC9B,OAAO,EAAE,OAAO,CAAA;IAChB,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;CAC1B;AAED,MAAM,WAAW,kBAAkB;IAClC,WAAW,EAAE,MAAM,CAAA;IACnB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,oFAAoF;IACpF,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,SAAS,CAAC,EAAE,MAAM,IAAI,CAAA;IACtB,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,IAAI,CAAA;CACrC;AAED,wBAAsB,WAAW,CAAC,IAAI,EAAE,kBAAkB,GAAG,OAAO,CAAC,cAAc,CAAC,CA4GnF;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CACnC,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,GAClC;IAAE,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;CAAE,CAmChC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAA;AAE1D,OAAO,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAA;AAC/D,YAAY,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAA;AAC9D,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAA;AACpD,OAAO,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAA;AACzD,YAAY,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AAyCzE,MAAM,WAAW,OAAO;IACvB,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,CAAA;CACZ;AAED,MAAM,WAAW,cAAc;IAC9B,OAAO,EAAE,OAAO,CAAA;IAChB,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;CAC1B;AAED,MAAM,WAAW,kBAAkB;IAClC,WAAW,EAAE,MAAM,CAAA;IACnB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,oFAAoF;IACpF,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,SAAS,CAAC,EAAE,MAAM,IAAI,CAAA;IACtB,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,IAAI,CAAA;IACrC;;;;OAIG;IACH,KAAK,CAAC,EAAE,CAAC,KAAK,EAAE,eAAe,KAAK,IAAI,CAAA;CACxC;AAED,wBAAsB,WAAW,CAAC,IAAI,EAAE,kBAAkB,GAAG,OAAO,CAAC,cAAc,CAAC,CAkKnF;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CACnC,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,GAClC;IAAE,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAAC,KAAK,EAAE,OAAO,CAAC,IAAI,CAAC,CAAA;CAAE,CA+CtD"}

package/dist/index.js

@@ -6,9 +6,13 @@ import { fileURLToPath } from 'node:url';
 import { createServer } from 'node:http';
 import { createRequire } from 'node:module';
 import chokidar from 'chokidar';
+import { createRebuildScheduler } from './rebuild-scheduler.js';
+import { createCompileWorker } from './compile-worker.js';
+export { createRebuildScheduler } from './rebuild-scheduler.js';
+export { filterDmccLogLine } from './compile-log.js';
+export { createCompileWorker } from './compile-worker.js';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const require = createRequire(import.meta.url);
-const build = require('@dimina/compiler');
 // esbuild's native binary is shipped inside node_modules, but when packaged
 // via electron-builder it lives in app.asar. asarUnpack puts the real binary
 // in app.asar.unpacked — but esbuild computes its binary path from __dirname,
@@ -35,22 +39,31 @@ function getRandomPort() {
     });
 }
 export async function openProject(opts) {
-    const { projectPath: rawProjectPath, port = 0, sourcemap = false, simulatorDir, containerDir: overrideContainerDir, outputDir, watch = true, onRebuild, onBuildError, } = opts;
+    const { projectPath: rawProjectPath, port = 0, sourcemap = false, simulatorDir, containerDir: overrideContainerDir, outputDir, watch = true, onRebuild, onBuildError, onLog, } = opts;
     const projectPath = path.resolve(rawProjectPath);
     const buildOptions = { sourcemap };
     const resolvedPort = port === 0 ? await getRandomPort() : port;
     const containerDir = overrideContainerDir ?? path.join(__dirname, '..', 'fe', 'dimina-fe-container');
-    const prevCwd = process.cwd();
     const resolvedOutputDir = outputDir
         ?? path.join(os.tmpdir(), 'dimina-kit', createHash('sha1').update(projectPath).digest('hex').slice(0, 12));
     fs.mkdirSync(resolvedOutputDir, { recursive: true });
+    // Compilation runs in a long-lived forked worker — the worker chdirs in
+    // its OWN process, so this (host) process never mutates its cwd, and dmcc
+    // terminal output arrives on the worker's piped streams (delivered to
+    // `onLog` line-by-line after `filterDmccLogLine`).
+    const compileWorker = createCompileWorker({ onLog });
+    const buildRequest = {
+        projectPath,
+        outputDir: resolvedOutputDir,
+        options: buildOptions,
+    };
     let initialAppInfo;
     try {
-        process.chdir(projectPath);
-        initialAppInfo = (await build(resolvedOutputDir, projectPath, true, buildOptions));
+        initialAppInfo = (await compileWorker.build(buildRequest));
     }
-    finally {
-        process.chdir(prevCwd);
+    catch (err) {
+        await compileWorker.close();
+        throw err;
     }
     // When the compiler is racing (e.g. opening a project that was just
     // closed elsewhere in the same Electron process) `build()` can return
@@ -81,25 +94,16 @@ export async function openProject(opts) {
         }
     }
     const sessionApps = initialAppInfo ? [initialAppInfo] : [];
-    process.env.DIMINA_NO_OPEN_BROWSER = '1';
-    const fe = await import('../fe/index.js');
-    const start = fe.start;
-    const { server, reload } = await start({
-        port: resolvedPort,
-        containerDir,
-        outputDir: resolvedOutputDir,
-        simulatorDir,
-        liveReload: true,
-        sessionApps,
-    });
-    let isBuilding = false;
+    // Everything after the worker exists is failure-cleaned: if the dev server
+    // or the watcher fails to come up, the already-forked compile worker (and a
+    // server that already started listening) must be torn down before the error
+    // propagates — otherwise every failed open leaks a whole compiler process.
+    let server = null;
+    let reload;
+    let watcher = null;
     async function rebuild() {
-        if (isBuilding)
-            return;
-        isBuilding = true;
         try {
-            process.chdir(projectPath);
-            const rebuilt = (await build(resolvedOutputDir, projectPath, true, buildOptions));
+            const rebuilt = (await compileWorker.build(buildRequest));
             if (rebuilt) {
                 const idx = sessionApps.findIndex(a => a.appId === rebuilt.appId);
                 if (idx === -1)
@@ -113,26 +117,79 @@ export async function openProject(opts) {
         catch (e) {
             onBuildError?.(e);
         }
-        finally {
-            process.chdir(prevCwd);
-            isBuilding = false;
+    }
+    try {
+        process.env.DIMINA_NO_OPEN_BROWSER = '1';
+        const fe = await import('../fe/index.js');
+        const start = fe.start;
+        const started = await start({
+            port: resolvedPort,
+            containerDir,
+            outputDir: resolvedOutputDir,
+            simulatorDir,
+            liveReload: true,
+            sessionApps,
+        });
+        server = started.server;
+        reload = started.reload;
+        // Watcher events are routed through the scheduler so a save landing while
+        // a build is in flight is never dropped: it coalesces into exactly one
+        // trailing rebuild once the current run settles.
+        const rebuildScheduler = createRebuildScheduler(rebuild);
+        watcher = watch ? createProjectWatcher(projectPath, () => rebuildScheduler.schedule()) : null;
+        // Don't resolve until the watcher's initial scan is done: a save landing
+        // in the gap between `openProject` resolving and chokidar going live
+        // (fsevents stream not yet active on macOS) would otherwise be silently
+        // missed — no rebuild for the very first post-open edit. The promise
+        // also REJECTS on a pre-ready watcher 'error' (EMFILE, permission loss)
+        // so a broken watcher fails the open instead of hanging it forever.
+        await watcher?.ready;
+    }
+    catch (err) {
+        try {
+            await watcher?.close();
+        }
+        catch {
+            // best-effort — the open is already failing with the primary error
+        }
+        try {
+            await compileWorker.close();
+        }
+        catch {
+            // best-effort — never mask the primary error
         }
+        if (server) {
+            ;
+            server.closeAllConnections?.();
+            const listening = server;
+            await new Promise(resolve => listening.close(() => resolve()));
+        }
+        throw err;
     }
-    const watcher = watch ? createProjectWatcher(projectPath, rebuild) : null;
+    // `server` is always assigned when the try block completes without throwing
+    // — this guard exists only to narrow the type for the close closure.
+    if (!server)
+        throw new Error('openProject: dev server missing after successful start');
+    const liveServer = server;
     return {
         appInfo: initialAppInfo ?? { appId: 'unknown', name: path.basename(projectPath), path: projectPath },
         port: resolvedPort,
         close: async () => {
             await watcher?.close();
-            server.closeAllConnections?.();
-            await new Promise(resolve => server.close(() => resolve()));
+            // Kill the long-lived compile worker and WAIT for the child to be
+            // actually dead — only kill, never re-fork on a graceful close (a
+            // refill here would wedge process teardown).
+            await compileWorker.close();
+            liveServer.closeAllConnections?.();
+            await new Promise(resolve => liveServer.close(() => resolve()));
         },
     };
 }
 /**
  * Watch a project directory and invoke `onChange` whenever a source file is
  * created, modified, or deleted. Returns a handle whose `close()` stops the
- * watcher.
+ * watcher and whose `ready` resolves once the initial scan is complete (only
+ * changes made after that point are guaranteed to surface).
  */
 export function createProjectWatcher(projectPath, onChange) {
     // Ignore dotfiles/dot-directories that live *inside* the project (.git,
@@ -166,7 +223,19 @@ export function createProjectWatcher(projectPath, onChange) {
     watcher.on('add', () => { void onChange(); });
     watcher.on('change', () => { void onChange(); });
     watcher.on('unlink', () => { void onChange(); });
+    // A watcher 'error' before the initial scan completes (EMFILE, permission
+    // loss, …) must REJECT `ready`: resolving only on 'ready' would leave
+    // `await watcher.ready` — and the whole openProject — hung forever. The
+    // listener also doubles as the EventEmitter unhandled-'error' guard. A
+    // post-ready 'error' makes the reject a settled-promise no-op.
+    const ready = new Promise((resolve, reject) => {
+        watcher.once('ready', () => resolve());
+        watcher.on('error', (err) => {
+            reject(err instanceof Error ? err : new Error(String(err)));
+        });
+    });
     return {
         close: () => watcher.close(),
+        ready,
     };
 }

package/dist/open-project-cleanup.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=open-project-cleanup.test.d.ts.map

package/dist/open-project-cleanup.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"open-project-cleanup.test.d.ts","sourceRoot":"","sources":["../src/open-project-cleanup.test.ts"],"names":[],"mappings":""}

package/dist/open-project-cleanup.test.js

@@ -0,0 +1,176 @@
+import { EventEmitter } from 'node:events';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { PassThrough } from 'node:stream';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import * as devkit from './index.js';
+/**
+ * CODEX-REVIEW REGRESSION WAVE (fix/editor-hot-reload-and-simulator-leftovers)
+ * — failing regression tests for review findings M4 / M6: resource cleanup
+ * when `openProject` fails AFTER the compile worker was already forked.
+ *
+ *  M4  the worker is created before the dev server starts; a server-start
+ *      failure propagates out of openProject but never kills the worker — a
+ *      leaked compiler process per failed open.
+ *  M6  `createProjectWatcher().ready` only resolves on chokidar's 'ready';
+ *      a watcher 'error' (EMFILE, permission loss, …) before ready leaves
+ *      `await watcher?.ready` — and therefore openProject — hung forever,
+ *      leaking the worker AND the already-listening dev server.
+ *
+ * Harness: same fake-fork pattern as compile-worker.test.ts, plus this file
+ * mocks the fe dev-server module and chokidar so the failure point of each
+ * test is injectable. All mocks are per-file (vi.mock is hoisted), so these
+ * tests live in their own file instead of the main orchestration suite.
+ */
+const mocks = vi.hoisted(() => ({
+    fork: vi.fn(),
+    feStart: vi.fn(),
+    watch: vi.fn(),
+}));
+vi.mock('node:child_process', async (importOriginal) => {
+    const actual = await importOriginal();
+    return { ...actual, fork: mocks.fork, default: { ...actual, fork: mocks.fork } };
+});
+vi.mock('child_process', async (importOriginal) => {
+    const actual = await importOriginal();
+    return { ...actual, fork: mocks.fork, default: { ...actual, fork: mocks.fork } };
+});
+// src/index.ts dynamically imports '../fe/index.js' and calls its `start`.
+vi.mock('../fe/index.js', () => ({ start: mocks.feStart }));
+vi.mock('chokidar', () => ({
+    default: { watch: mocks.watch },
+    watch: mocks.watch,
+}));
+/** Minimal auto-responding fake compile worker (kill spy is the assertion). */
+class FakeChild extends EventEmitter {
+    stdout = new PassThrough();
+    stderr = new PassThrough();
+    connected = true;
+    pid = 4242;
+    send = vi.fn((msg) => {
+        const m = msg;
+        if (m && m.cmd === 'build') {
+            queueMicrotask(() => {
+                if (!this.connected)
+                    return;
+                this.emit('message', {
+                    type: 'result',
+                    appInfo: { appId: 'cleanup_app_001', name: 'cleanup-app', path: String(m.projectPath ?? '') },
+                });
+            });
+        }
+        return true;
+    });
+    kill = vi.fn(() => {
+        this.connected = false;
+        queueMicrotask(() => this.emit('exit', null, 'SIGTERM'));
+        return true;
+    });
+}
+/** chokidar stand-in: an EventEmitter with the watcher surface index.ts uses. */
+class FakeWatcher extends EventEmitter {
+    close = vi.fn(async () => { });
+}
+function makeFakeFe() {
+    const server = {
+        close: vi.fn((cb) => {
+            cb?.();
+            return server;
+        }),
+        closeAllConnections: vi.fn(),
+    };
+    return { server, reload: vi.fn() };
+}
+const children = [];
+const watchers = [];
+const feInstances = [];
+const cleanupRoots = [];
+beforeEach(() => {
+    children.length = 0;
+    watchers.length = 0;
+    feInstances.length = 0;
+    mocks.fork.mockReset();
+    mocks.fork.mockImplementation(() => {
+        const child = new FakeChild();
+        children.push(child);
+        return child;
+    });
+    mocks.feStart.mockReset();
+    mocks.feStart.mockImplementation(async () => {
+        const fe = makeFakeFe();
+        feInstances.push(fe);
+        return fe;
+    });
+    mocks.watch.mockReset();
+    mocks.watch.mockImplementation(() => {
+        const watcher = new FakeWatcher();
+        watchers.push(watcher);
+        // Well-behaved default: initial scan completes promptly.
+        queueMicrotask(() => watcher.emit('ready'));
+        return watcher;
+    });
+});
+afterEach(() => {
+    for (const root of cleanupRoots.splice(0)) {
+        fs.rmSync(root, { recursive: true, force: true });
+    }
+});
+function makeFixture() {
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), 'devkit-open-cleanup-'));
+    cleanupRoots.push(root);
+    fs.writeFileSync(path.join(root, 'project.config.json'), JSON.stringify({ appid: 'cleanup_app_001', projectname: 'cleanup-app' }));
+    return root;
+}
+function sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+describe('openProject failure cleanup — no leaked compile worker (codex M4/M6)', () => {
+    it('M4: a dev-server start failure AFTER the worker was forked rejects openProject AND kills the worker', async () => {
+        const root = makeFixture();
+        mocks.feStart.mockReset();
+        mocks.feStart.mockRejectedValue(new Error('listen EADDRINUSE: address already in use'));
+        await expect(devkit.openProject({
+            projectPath: root,
+            watch: false,
+            outputDir: path.join(root, '.out'),
+        })).rejects.toThrow(/EADDRINUSE/);
+        expect(children.length, 'precondition: the compile worker is forked BEFORE the dev server starts').toBe(1);
+        expect(children[0].kill, 'a server-start failure must kill the already-forked compile worker — today the error propagates but the '
+            + 'worker (a whole compiler process) is leaked on every failed open').toHaveBeenCalled();
+    }, 15_000);
+    it("M6: a watcher 'error' before 'ready' rejects openProject within a bounded time and kills the worker (no eternal hang)", async () => {
+        const root = makeFixture();
+        mocks.watch.mockReset();
+        mocks.watch.mockImplementation(() => {
+            const watcher = new FakeWatcher();
+            watchers.push(watcher);
+            setTimeout(() => {
+                // Today nothing listens for 'error' (EventEmitter would throw on
+                // an unhandled 'error' event) — the swallow keeps THIS test
+                // deterministic; the bug is that openProject then hangs forever.
+                try {
+                    watcher.emit('error', new Error('EMFILE: too many open files, watch'));
+                }
+                catch {
+                    // no 'error' listener registered — the exact gap under test
+                }
+            }, 10);
+            return watcher;
+        });
+        const openPromise = devkit.openProject({
+            projectPath: root,
+            watch: true,
+            outputDir: path.join(root, '.out'),
+        });
+        const outcome = await Promise.race([
+            openPromise.then(() => 'resolved', () => 'rejected'),
+            sleep(3000).then(() => 'hung'),
+        ]);
+        expect(outcome, "a watcher 'error' before the initial scan completes must REJECT openProject — `await watcher.ready` only "
+            + "listens for 'ready', so today the open hangs forever").toBe('rejected');
+        expect(children.length, 'precondition: the compile worker was forked before the watcher failed').toBe(1);
+        expect(children[0].kill, 'the watcher-error rejection must clean up the already-created resources: the compile worker must be killed').toHaveBeenCalled();
+        expect(feInstances[0]?.server.close, '…and the already-listening dev server must be closed too').toHaveBeenCalled();
+    }, 15_000);
+});

package/dist/open-project-compile-log.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=open-project-compile-log.test.d.ts.map

package/dist/open-project-compile-log.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"open-project-compile-log.test.d.ts","sourceRoot":"","sources":["../src/open-project-compile-log.test.ts"],"names":[],"mappings":""}

package/dist/open-project-compile-log.test.js

@@ -0,0 +1,174 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { afterEach, describe, expect, it } from 'vitest';
+import * as devkit from './index.js';
+import { writeUntilSettled } from './watch-rebuild.testutil.js';
+const cleanupRoots = [];
+const openSessions = [];
+afterEach(async () => {
+    for (const session of openSessions.splice(0)) {
+        try {
+            await session.close();
+        }
+        catch {
+            // best-effort teardown
+        }
+    }
+    for (const root of cleanupRoots.splice(0)) {
+        fs.rmSync(root, { recursive: true, force: true });
+    }
+});
+function makeFixture(opts = {}) {
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), 'devkit-compile-log-'));
+    cleanupRoots.push(root);
+    const write = (rel, content) => {
+        const target = path.join(root, rel);
+        fs.mkdirSync(path.dirname(target), { recursive: true });
+        fs.writeFileSync(target, content);
+    };
+    write('project.config.json', JSON.stringify({ appid: 'fixture_app_001', projectname: 'fixture-app' }));
+    write('app.json', JSON.stringify({ pages: ['pages/index/index'] }));
+    write('app.js', 'App({})\n');
+    write('app.wxss', 'page { font-size: 14px; }\n');
+    write('pages/index/index.json', '{}\n');
+    write('pages/index/index.js', opts.brokenIndexJs
+        // Unbalanced brace + bad tokens — same corruption shape the spike used
+        // to capture error.stderr.txt (esbuild transform failure).
+        ? 'Page({ data: { msg: "hi" } })\nconst broken = {{{ ;;; <<<\n'
+        : 'Page({ data: { msg: "hi" } })\n');
+    write('pages/index/index.wxml', '<view>{{msg}}</view>\n');
+    write('pages/index/index.wxss', '.x { color: red; }\n');
+    return root;
+}
+/** Noise patterns that must NEVER reach onLog (RESULTS.md §③ DROP rules). */
+function expectNoNoise(texts) {
+    for (const text of texts) {
+        expect(text.length, 'onLog must never receive an empty line').toBeGreaterThan(0);
+        expect(text, 'logo / box-drawing banner lines must be filtered out').not.toMatch(/^[█╔╗╚╝═║\s]+$/);
+        expect(text, '`❯ ` task-start lines must be filtered out').not.toMatch(/^❯ /);
+        expect(text, '`› [██░░] %` progress-bar lines must be filtered out').not.toMatch(/^› \[/);
+        expect(text, 'fe-server banner must be filtered out').not.toMatch(/^Server is running/);
+        expect(text, 'fe-server banner must be filtered out').not.toMatch(/^Press Ctrl\+C/);
+        expect(text, 'stack-trace frames must be filtered out').not.toMatch(/^\s+at /);
+    }
+}
+describe('openProject onLog — first compile (integration, real dmcc)', () => {
+    it('streams filtered compile-error lines to onLog when the first compile fails', async () => {
+        const root = makeFixture({ brokenIndexJs: true });
+        const entries = [];
+        const logOpts = { onLog: (entry) => entries.push(entry) };
+        const session = await devkit.openProject({
+            projectPath: root,
+            watch: false,
+            outputDir: path.join(root, '.out'),
+            ...logOpts,
+        });
+        openSessions.push(session);
+        expect(entries.length, 'openProject must wire opts.onLog through withCapturedStdio around the first build() — no lines were captured').toBeGreaterThan(0);
+        const texts = entries.map(entry => entry.text);
+        expect(texts.some(text => /esbuild 转换失败/.test(text)), 'the `[logic] esbuild 转换失败 <file>` line is the highest-value error line and must be kept').toBe(true);
+        expect(texts.some(text => /^✖ /.test(text)), '`✖ …[FAILED: …]` listr failure lines must be kept').toBe(true);
+        expect(texts.some(text => /编译出错: /.test(text)), 'the `… 编译出错: …` summary line must be kept').toBe(true);
+        expectNoNoise(texts);
+        for (const entry of entries) {
+            expect(['stdout', 'stderr']).toContain(entry.stream);
+            expect(typeof entry.text).toBe('string');
+        }
+        // dmcc emits the esbuild failure on stderr (error.stderr.txt line 1) —
+        // the stream tag must say so, so the panel can style it as an error.
+        const failure = entries.find(entry => /esbuild 转换失败/.test(entry.text));
+        expect(failure?.stream).toBe('stderr');
+    }, 60_000);
+    it('streams filtered stage lines (✔ …) to onLog on a successful first compile', async () => {
+        const root = makeFixture();
+        const entries = [];
+        const logOpts = { onLog: (entry) => entries.push(entry) };
+        const session = await devkit.openProject({
+            projectPath: root,
+            watch: false,
+            outputDir: path.join(root, '.out'),
+            ...logOpts,
+        });
+        openSessions.push(session);
+        expect(entries.length, 'a successful compile must also stream its stage lines through onLog').toBeGreaterThan(0);
+        const texts = entries.map(entry => entry.text);
+        expect(texts.some(text => /^✔ /.test(text)), '`✔ ` stage-completion lines must be kept (e.g. ✔ 输出编译产物)').toBe(true);
+        expectNoNoise(texts);
+        // Stage lines are stdout (success.stdout.txt) — stream tags must match.
+        const stage = entries.find(entry => /^✔ /.test(entry.text));
+        expect(stage?.stream).toBe('stdout');
+    }, 60_000);
+});
+describe('openProject onLog — watcher rebuild (integration, real dmcc)', () => {
+    it('streams rebuild lines to onLog when the file watcher triggers a rebuild', async () => {
+        const root = makeFixture();
+        const entries = [];
+        const logOpts = { onLog: (entry) => entries.push(entry) };
+        let resolveRebuilt = () => { };
+        const rebuilt = new Promise((resolve) => {
+            resolveRebuilt = resolve;
+        });
+        const session = await devkit.openProject({
+            projectPath: root,
+            watch: true,
+            outputDir: path.join(root, '.out'),
+            // rebuild() invokes onRebuild AFTER build() resolves, so by the time
+            // this fires every rebuild log line has already been delivered.
+            onRebuild: () => resolveRebuilt(),
+            ...logOpts,
+        });
+        openSessions.push(session);
+        // Only count lines captured by the REBUILD build() call.
+        entries.length = 0;
+        // Count-agnostic (entries.length > 0): re-write until the rebuild lands so
+        // a dropped inotify event under CI load can't hang `await rebuilt`.
+        await writeUntilSettled(rebuilt, path.join(root, 'pages', 'index', 'index.js'), attempt => `Page({ data: { msg: "updated-${attempt}" } })\n`);
+        expect(entries.length, 'the rebuild() build() call must ALSO be wrapped with withCapturedStdio — no rebuild lines reached onLog').toBeGreaterThan(0);
+        const texts = entries.map(entry => entry.text);
+        expect(texts.some(text => /^✔ /.test(text)), 'rebuild stage-completion lines must be kept').toBe(true);
+        expectNoNoise(texts);
+    }, 60_000);
+});
+describe('openProject without onLog — zero-overhead contract (regression guard, green today)', () => {
+    it('never swaps process.stdout/stderr.write nor touches isTTY during the build', async () => {
+        const root = makeFixture();
+        const stdoutM = process.stdout;
+        const stderrM = process.stderr;
+        const before = {
+            outWrite: stdoutM.write,
+            errWrite: stderrM.write,
+            outTTY: stdoutM.isTTY,
+            errTTY: stderrM.isTTY,
+        };
+        let writeSwapped = false;
+        let ttyTouched = false;
+        let samples = 0;
+        // The build awaits worker threads / esbuild IPC, so the event loop turns
+        // freely during the multi-second compile — the sampler reliably lands
+        // inside the build window.
+        const timer = setInterval(() => {
+            samples += 1;
+            if (stdoutM.write !== before.outWrite || stderrM.write !== before.errWrite) {
+                writeSwapped = true;
+            }
+            if (stdoutM.isTTY !== before.outTTY || stderrM.isTTY !== before.errTTY) {
+                ttyTouched = true;
+            }
+        }, 1);
+        try {
+            const session = await devkit.openProject({
+                projectPath: root,
+                watch: false,
+                outputDir: path.join(root, '.out'),
+            });
+            openSessions.push(session);
+        }
+        finally {
+            clearInterval(timer);
+        }
+        expect(samples, 'sampler must have observed the build window').toBeGreaterThan(20);
+        expect(writeSwapped, 'without onLog the capture wrapper must NOT be engaged — write was swapped during the build').toBe(false);
+        expect(ttyTouched, 'without onLog isTTY must stay untouched during the build').toBe(false);
+    }, 60_000);
+});

package/dist/rebuild-scheduler.d.ts

@@ -0,0 +1,24 @@
+export interface RebuildScheduler {
+    /** Request a rebuild. Coalesces with any in-flight or already-pending run. */
+    schedule: () => void;
+}
+/**
+ * Serialize rebuild runs with a dirty-flag + trailing rerun, replacing the old
+ * `if (isBuilding) return` early-exit in `openProject`'s rebuild loop, which
+ * silently DROPPED any watcher event that landed while a build was in flight
+ * (a save made during the ~1-2s compile window never produced a rebuild — the
+ * simulator stayed stale until the user saved again).
+ *
+ * Semantics:
+ *  - `schedule()` while idle starts `run` immediately.
+ *  - `schedule()` while `run` is in flight never starts a concurrent run
+ *    (`build()` chdir()s into the project — concurrency would corrupt cwd);
+ *    it marks the state dirty instead.
+ *  - When the in-flight run settles and the state is dirty, exactly one
+ *    trailing run starts: N saves during one build coalesce into 1 rerun.
+ *    The trailing run is itself schedulable-against, recursively.
+ *  - A rejecting run neither wedges the scheduler nor drops a pending dirty
+ *    flag — `run` is expected to do its own error reporting (`onBuildError`).
+ */
+export declare function createRebuildScheduler(run: () => Promise<void>): RebuildScheduler;
+//# sourceMappingURL=rebuild-scheduler.d.ts.map

package/dist/rebuild-scheduler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rebuild-scheduler.d.ts","sourceRoot":"","sources":["../src/rebuild-scheduler.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,gBAAgB;IAChC,8EAA8E;IAC9E,QAAQ,EAAE,MAAM,IAAI,CAAA;CACpB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,gBAAgB,CAwCjF"}