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

package/README.md

@@ -49,6 +49,7 @@ await session.close()
 | `watch`        | `boolean`                | `true`  | 为 `false` 时跳过 chokidar 文件监听 / 自动重编译循环                                        |
 | `onRebuild`    | `() => void`             | --      | 文件变更触发重新编译后的回调                                                                 |
 | `onBuildError` | `(err: unknown) => void` | --      | 编译出错时的回调                                                                             |
+| `onLog`        | `(entry) => void`        | --      | 逐行编译日志回调；`entry = { stream: 'stdout' \| 'stderr', text }`，已经过内置噪音过滤（`filterDmccLogLine`） |
 
 #### 返回值 ProjectSession
 
@@ -62,9 +63,10 @@ await session.close()
 
 ## 工作流程
 
-1. 调用 `@dimina/compiler` 编译小程序项目
-2. 启动基于 Express 的 H5 容器预览服务器（含 CORS、SPA fallback、可选 live-reload）
-3. 通过 chokidar 监听项目目录变更，自动触发增量编译和页面刷新
+1. 在 fork 出的长驻编译子进程中调用 `@dimina/compiler` 编译小程序项目（cwd 隔离：`chdir` 只发生在子进程内，宿主进程 cwd 不被污染；编译器崩溃不会拖垮宿主，下次重编译自动重新 fork 恢复）
+2. 子进程的 stdout/stderr 按行管道回父进程，经 `filterDmccLogLine` 过滤噪音后通过 `onLog` 回调送出
+3. 启动基于 Express 的 H5 容器预览服务器（含 CORS、SPA fallback、可选 live-reload）
+4. 通过 chokidar 监听项目目录变更，自动触发增量编译和页面刷新；编译进行中的变更不会丢失，会在当前编译结束后合并为恰好一次尾随重编译（trailing rebuild）
 
 ---
 

package/dist/compile-log.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Pure line filter for dmcc (`@dimina/compiler`) terminal output.
+ *
+ * The compiler + its listr2 renderer write directly to stdout/stderr. In the
+ * fork architecture the parent reads the worker's piped streams and runs every
+ * line through this filter before delivering it to `onLog`. DROP rules are
+ * derived from real captured output (`.repro/dmcc-log-spike/`); everything
+ * else is KEPT (default-keep), so unanticipated high-value lines — e.g.
+ * esbuild's `<stdin>:L:C: ERROR: …` detail — always survive.
+ */
+/**
+ * Strip ANSI escapes, then decide keep/drop. Returns the cleaned line, or
+ * `null` when the line is known noise (or empty once stripped).
+ */
+export declare function filterDmccLogLine(line: string): string | null;
+//# sourceMappingURL=compile-log.d.ts.map

package/dist/compile-log.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compile-log.d.ts","sourceRoot":"","sources":["../src/compile-log.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAsBH;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAO7D"}

package/dist/compile-log.js

@@ -0,0 +1,42 @@
+/**
+ * Pure line filter for dmcc (`@dimina/compiler`) terminal output.
+ *
+ * The compiler + its listr2 renderer write directly to stdout/stderr. In the
+ * fork architecture the parent reads the worker's piped streams and runs every
+ * line through this filter before delivering it to `onLog`. DROP rules are
+ * derived from real captured output (`.repro/dmcc-log-spike/`); everything
+ * else is KEPT (default-keep), so unanticipated high-value lines — e.g.
+ * esbuild's `<stdin>:L:C: ERROR: …` detail — always survive.
+ */
+// CSI escape sequences (colors, erase-line, cursor moves) as emitted by
+// chalk / listr2 TTY renderers.
+// eslint-disable-next-line no-control-regex
+const ANSI_RE = /\u001B\[[0-9;?]*[ -/]*[@-~]/g;
+const DROP_RULES = [
+    // dmcc logo banner (art.js): box-drawing characters only.
+    /^[█╔╗╚╝═║\s]+$/,
+    // `❯ ` listr task-start lines — transient noise; ✔/✖ cover the outcome.
+    /^❯ /,
+    // `› [██░░] %` per-worker progress-bar lines.
+    /^› \[/,
+    // devkit fe-server banner — the port is already surfaced via session.port.
+    /^Server is running on port /,
+    /^Press Ctrl\+C to stop/,
+    // Stack-trace frames (esbuild / Node internals) — the message line above
+    // them is kept; frames are noise for a compile panel.
+    /^\s+at /,
+];
+/**
+ * Strip ANSI escapes, then decide keep/drop. Returns the cleaned line, or
+ * `null` when the line is known noise (or empty once stripped).
+ */
+export function filterDmccLogLine(line) {
+    const cleaned = line.replace(ANSI_RE, '');
+    if (cleaned.trim() === '')
+        return null;
+    for (const rule of DROP_RULES) {
+        if (rule.test(cleaned))
+            return null;
+    }
+    return cleaned;
+}

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

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

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

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

package/dist/compile-log.test.js

@@ -0,0 +1,134 @@
+import { describe, expect, it } from 'vitest';
+import * as devkit from './index.js';
+function getFilter() {
+    const fn = devkit.filterDmccLogLine;
+    expect(typeof fn, 'devkit must export filterDmccLogLine(line): string | null — the pure dmcc noise filter (re-exported from the new compile-log module via src/index.ts)').toBe('function');
+    return fn;
+}
+describe('filterDmccLogLine — DROP rules (real dmcc noise from the spike archives)', () => {
+    // success.stdout.txt lines 4-9: the dmcc logo banner (art.js). Printed
+    // only on the first build of a process, but must always be stripped.
+    const LOGO_LINES = [
+        '██████╗ ██╗███╗   ███╗██╗███╗   ██╗ █████╗',
+        '██╔══██╗██║████╗ ████║██║████╗  ██║██╔══██╗',
+        '██║  ██║██║██╔████╔██║██║██╔██╗ ██║███████║',
+        '██║  ██║██║██║╚██╔╝██║██║██║╚██╗██║██╔══██║',
+        '██████╔╝██║██║ ╚═╝ ██║██║██║ ╚████║██║  ██║',
+        '╚═════╝ ╚═╝╚═╝     ╚═╝╚═╝╚═╝  ╚═══╝╚═╝  ╚═╝',
+    ];
+    it('drops every logo / box-drawing banner line', () => {
+        const filter = getFilter();
+        for (const line of LOGO_LINES) {
+            expect(filter(line), `logo line must be dropped: ${JSON.stringify(line)}`).toBeNull();
+        }
+    });
+    it('drops blank and whitespace-only lines (logo surroundings)', () => {
+        const filter = getFilter();
+        expect(filter('')).toBeNull();
+        expect(filter('   ')).toBeNull();
+        expect(filter('\t')).toBeNull();
+    });
+    it('drops `❯ ` listr task-start lines (transient — ✔/✖ already cover them)', () => {
+        const filter = getFilter();
+        // success.stdout.txt lines 11 / 21
+        expect(filter('❯ 准备项目编译环境')).toBeNull();
+        expect(filter('❯ 开始编译:demo-app')).toBeNull();
+        expect(filter('❯ 编译页面逻辑')).toBeNull();
+    });
+    it('drops `› [██░░] %` progress-bar lines', () => {
+        const filter = getFilter();
+        // success.stdout.txt lines 25 / 32 / 43
+        expect(filter('› [████░░░░░░░░░░░░░░░░░░░░░░░░░░] 12.50%')).toBeNull();
+        expect(filter('› [██████████████████████████████] 100.00%')).toBeNull();
+        expect(filter('› [███████░░░░░░░░░░░░░░░░░░░░░░░] 22.22%')).toBeNull();
+    });
+    it('drops the devkit fe-server lines (port is already surfaced via session.port)', () => {
+        const filter = getFilter();
+        // success.stdout.txt lines 56-57
+        expect(filter('Server is running on port 52197')).toBeNull();
+        expect(filter('Press Ctrl+C to stop')).toBeNull();
+    });
+    it('drops stack-trace frames (esbuild/Node internals)', () => {
+        const filter = getFilter();
+        // error.stderr.txt lines 20-29
+        expect(filter('    at failureErrorWithLog (/Volumes/jdisk/code/dimina-kit/node_modules/.pnpm/esbuild@0.28.0/node_modules/esbuild/lib/main.js:1748:15)')).toBeNull();
+        expect(filter('    at /Volumes/jdisk/code/dimina-kit/node_modules/.pnpm/esbuild@0.28.0/node_modules/esbuild/lib/main.js:1017:50')).toBeNull();
+        expect(filter('    at Socket.emit (node:events:507:28)')).toBeNull();
+        expect(filter('    at Pipe.onStreamRead (node:internal/stream_base_commons:189:23)')).toBeNull();
+    });
+});
+describe('filterDmccLogLine — KEEP rules (real dmcc signal from the spike archives)', () => {
+    it('keeps the `[logic]` esbuild transform-failure line (the highest-value error line)', () => {
+        const filter = getFilter();
+        // error.stderr.txt line 1
+        const line = '[logic] esbuild 转换失败 /Volumes/jdisk/code/dimina-kit/packages/demo-app/pages/index/index.js: Transform failed with 1 error:';
+        expect(filter(line), 'esbuild 转换失败 must be kept — it carries the failing file path').toBe(line);
+    });
+    it('keeps the esbuild `<stdin>:L:C: ERROR:` detail line (default-keep for unrecognized content)', () => {
+        const filter = getFilter();
+        // error.stderr.txt line 2 — the actual syntax-error location. It matches
+        // no DROP rule and MUST survive: a whitelist-only filter would lose the
+        // only line that tells the developer what is wrong.
+        const line = '<stdin>:96:16: ERROR: Expected identifier but found "{"';
+        expect(filter(line)).toBe(line);
+    });
+    it('keeps `[logic]/[view]/[style]/[compat]` prefixed warnings', () => {
+        const filter = getFilter();
+        // success.stderr.txt lines 1 / 2 / 10 / 11
+        const lines = [
+            '[logic] 检测到循环依赖: pages/component-test/component-test -> /components/nested-item/nested-item -> /components/nested-item/nested-item',
+            '[compat] Unsupported wx API: wx.createInnerAudioContext (/pages/audio-test/audio-test.js:33)',
+            '[view] 检测到循环依赖，跳过处理: /components/nested-item/nested-item',
+            '[style] 检测到循环依赖: pages/component-test/component-test -> /components/nested-item/nested-item -> /components/nested-item/nested-item',
+        ];
+        for (const line of lines) {
+            expect(filter(line), `prefixed warning must be kept: ${JSON.stringify(line)}`).toBe(line);
+        }
+    });
+    it('keeps `✖ ` listr failure lines (with the FAILED reason)', () => {
+        const filter = getFilter();
+        // error.stderr.txt lines 12 / 14
+        const lines = [
+            '✖ 编译页面逻辑 [FAILED: Transform failed with 1 error:',
+            '✖ 开始编译:demo-app [FAILED: Transform failed with 1 error:',
+        ];
+        for (const line of lines) {
+            expect(filter(line)).toBe(line);
+        }
+    });
+    it('keeps the `编译出错: ` summary line', () => {
+        const filter = getFilter();
+        // error.stderr.txt line 16
+        const line = '/Volumes/jdisk/code/dimina-kit/packages/demo-app 编译出错: Transform failed with 1 error:';
+        expect(filter(line)).toBe(line);
+    });
+    it('keeps `✔ ` stage-completion lines', () => {
+        const filter = getFilter();
+        // success.stdout.txt lines 13 / 33 / 53 / 55
+        const lines = [
+            '✔ 收集配置信息',
+            '✔ 编译页面逻辑',
+            '✔ 开始编译:demo-app',
+            '✔ 输出编译产物',
+        ];
+        for (const line of lines) {
+            expect(filter(line)).toBe(line);
+        }
+    });
+});
+describe('filterDmccLogLine — ANSI stripping happens BEFORE rule matching', () => {
+    it('strips ANSI from a kept line and returns the cleaned text', () => {
+        const filter = getFilter();
+        expect(filter('\u001B[32m✔\u001B[39m 收集配置信息')).toBe('✔ 收集配置信息');
+    });
+    it('drops an ANSI-wrapped progress line (rules apply to the stripped text)', () => {
+        const filter = getFilter();
+        // What a TTY listr renderer chunk looks like: erase-line + column-1
+        // escapes around the same progress payload.
+        expect(filter('\u001B[2K\u001B[1G› [██████████████████████████████] 100.00%')).toBeNull();
+    });
+    it('drops a line that is empty once ANSI is stripped', () => {
+        const filter = getFilter();
+        expect(filter('\u001B[2K\u001B[1G')).toBeNull();
+    });
+});

package/dist/compile-worker-entry.d.ts

@@ -0,0 +1,47 @@
+export interface WorkerAppInfo {
+    appId: string;
+    name: string;
+    path: string;
+}
+export interface WorkerBuildOptions {
+    sourcemap?: boolean;
+}
+export type WorkerBuildFn = (outputDir: string, projectPath: string, useAppIdDir: boolean, options: WorkerBuildOptions) => Promise<WorkerAppInfo | null | undefined>;
+export interface WorkerResultMessage {
+    type: 'result';
+    appInfo: WorkerAppInfo | null;
+    error?: {
+        message: string;
+    };
+}
+export interface CompileWorkerHandlerDeps {
+    /** Lazy `require('@dimina/compiler')` — deferred to the first build. */
+    loadCompiler: () => WorkerBuildFn;
+    /** `process.chdir` — mutates the CHILD process cwd only. */
+    chdir: (dir: string) => void;
+    /** `process.send` — replies to the parent. */
+    send: (msg: WorkerResultMessage) => void;
+}
+/**
+ * Build the fork-side IPC message handler. Non-build messages are ignored
+ * (no compiler load, no reply). A build command chdirs into the project,
+ * runs the compiler exactly as the old in-process call sites did, and ALWAYS
+ * replies — `@dimina/compiler` swallows compile errors internally (resolves
+ * undefined), which is normalized to `appInfo: null`; a genuine throw still
+ * replies with `error.message` so the parent never hangs on a lost build.
+ */
+export declare function createCompileWorkerHandler(deps: CompileWorkerHandlerDeps): (msg: unknown) => Promise<void>;
+/**
+ * Wire a worker process to its message handler. Extracted so the fork-mode
+ * self-wiring below and unit tests exercise the SAME wiring code (an inline
+ * copy next to an exported one would drift apart silently).
+ *
+ * Both subscriptions are registered synchronously at call time — an async gap
+ * between fork and the 'disconnect' subscription is a window where a dying
+ * parent leaks the child as an orphan.
+ */
+export declare function wireCompileWorkerProcess(proc: {
+    on: (event: 'message' | 'disconnect', listener: (...args: unknown[]) => void) => unknown;
+    exit: (code?: number) => void;
+}, handler: (msg: unknown) => Promise<void>): void;
+//# sourceMappingURL=compile-worker-entry.d.ts.map

package/dist/compile-worker-entry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compile-worker-entry.d.ts","sourceRoot":"","sources":["../src/compile-worker-entry.ts"],"names":[],"mappings":"AAkBA,MAAM,WAAW,aAAa;IAC7B,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,CAAA;CACZ;AAED,MAAM,WAAW,kBAAkB;IAClC,SAAS,CAAC,EAAE,OAAO,CAAA;CACnB;AAED,MAAM,MAAM,aAAa,GAAG,CAC3B,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,OAAO,EACpB,OAAO,EAAE,kBAAkB,KACvB,OAAO,CAAC,aAAa,GAAG,IAAI,GAAG,SAAS,CAAC,CAAA;AAE9C,MAAM,WAAW,mBAAmB;IACnC,IAAI,EAAE,QAAQ,CAAA;IACd,OAAO,EAAE,aAAa,GAAG,IAAI,CAAA;IAC7B,KAAK,CAAC,EAAE;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,CAAA;CAC3B;AAED,MAAM,WAAW,wBAAwB;IACxC,wEAAwE;IACxE,YAAY,EAAE,MAAM,aAAa,CAAA;IACjC,4DAA4D;IAC5D,KAAK,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAA;IAC5B,8CAA8C;IAC9C,IAAI,EAAE,CAAC,GAAG,EAAE,mBAAmB,KAAK,IAAI,CAAA;CACxC;AAiBD;;;;;;;GAOG;AACH,wBAAgB,0BAA0B,CACzC,IAAI,EAAE,wBAAwB,GAC5B,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC,IAAI,CAAC,CAwBjC;AAED;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,CACvC,IAAI,EAAE;IACL,EAAE,EAAE,CAAC,KAAK,EAAE,SAAS,GAAG,YAAY,EAAE,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,KAAK,OAAO,CAAA;IACxF,IAAI,EAAE,CAAC,IAAI,CAAC,EAAE,MAAM,KAAK,IAAI,CAAA;CAC7B,EACD,OAAO,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC,IAAI,CAAC,GACtC,IAAI,CASN"}

package/dist/compile-worker-entry.js

@@ -0,0 +1,117 @@
+/**
+ * `child_process.fork()` target for the long-lived compile worker.
+ *
+ * Compilation runs OUT of the host (Electron main) process so that:
+ *  - `process.chdir(projectPath)` mutates the WORKER's cwd, never the host's,
+ *  - dmcc/listr2 output lands on the worker's piped stdout/stderr (read
+ *    line-by-line by the parent — no global write-hooks, no isTTY hacks),
+ *  - a compiler crash kills the worker, not the host.
+ *
+ * Zero-dependency thin shell: the compiler is required lazily on the first
+ * build command and cached for the worker's lifetime. The IPC handling lives
+ * in `createCompileWorkerHandler` (dependency-injected) so it is unit-testable
+ * without forking.
+ */
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+function isBuildMessage(msg) {
+    return (typeof msg === 'object'
+        && msg !== null
+        && msg.cmd === 'build');
+}
+/**
+ * Build the fork-side IPC message handler. Non-build messages are ignored
+ * (no compiler load, no reply). A build command chdirs into the project,
+ * runs the compiler exactly as the old in-process call sites did, and ALWAYS
+ * replies — `@dimina/compiler` swallows compile errors internally (resolves
+ * undefined), which is normalized to `appInfo: null`; a genuine throw still
+ * replies with `error.message` so the parent never hangs on a lost build.
+ */
+export function createCompileWorkerHandler(deps) {
+    let cachedBuild = null;
+    return async (msg) => {
+        if (!isBuildMessage(msg))
+            return;
+        try {
+            if (!cachedBuild)
+                cachedBuild = deps.loadCompiler();
+            deps.chdir(msg.projectPath);
+            const appInfo = await cachedBuild(msg.outputDir, msg.projectPath, true, msg.options);
+            deps.send({ type: 'result', appInfo: appInfo ?? null });
+        }
+        catch (err) {
+            deps.send({
+                type: 'result',
+                appInfo: null,
+                error: { message: err instanceof Error ? err.message : String(err) },
+            });
+        }
+    };
+}
+/**
+ * Wire a worker process to its message handler. Extracted so the fork-mode
+ * self-wiring below and unit tests exercise the SAME wiring code (an inline
+ * copy next to an exported one would drift apart silently).
+ *
+ * Both subscriptions are registered synchronously at call time — an async gap
+ * between fork and the 'disconnect' subscription is a window where a dying
+ * parent leaks the child as an orphan.
+ */
+export function wireCompileWorkerProcess(proc, handler) {
+    proc.on('message', (msg) => {
+        void handler(msg);
+    });
+    // The parent kills the worker on session close; if the parent dies first
+    // (IPC channel gone), exit instead of lingering as an orphan.
+    proc.on('disconnect', () => {
+        proc.exit(0);
+    });
+}
+// ── Fork-mode self-wiring ───────────────────────────────────────────────────
+//
+// Only engage when this module IS the forked entry: argv[1] must be EXACTLY
+// this module's own file (normalized-path comparison against import.meta.url),
+// not merely a path containing the substring 'compile-worker-entry' — a
+// substring gate would let any unrelated IPC-child script whose path happens
+// to contain that fragment import this module and get its process hijacked
+// (a disconnect→exit(0) handler + a message handler stealing IPC traffic).
+// A plain `process.send` check is not enough either: vitest's default "forks"
+// pool also runs test workers as IPC children, and importing this module from
+// a unit test must stay side-effect free there.
+//
+// `stripModuleQuery` drops a `?query` / `#hash` suffix before comparing —
+// dev-time loaders (vite-node/vitest) append cache-busting queries like
+// `?v=…` to module URLs, which fileURLToPath would choke on and which never
+// appear in the real argv[1].
+function stripModuleQuery(spec) {
+    return spec.replace(/[?#].*$/, '');
+}
+const selfModulePath = (() => {
+    try {
+        return path.resolve(fileURLToPath(stripModuleQuery(import.meta.url)));
+    }
+    catch {
+        // Non-file module URL (bundler virtual module etc.) — never the fork
+        // target, so the gate simply stays disengaged.
+        return null;
+    }
+})();
+const isForkedWorkerEntry = typeof process.argv[1] === 'string'
+    && selfModulePath !== null
+    && path.resolve(stripModuleQuery(process.argv[1])) === selfModulePath
+    && typeof process.send === 'function';
+if (isForkedWorkerEntry) {
+    const require = createRequire(import.meta.url);
+    const handler = createCompileWorkerHandler({
+        loadCompiler: () => require('@dimina/compiler'),
+        chdir: dir => process.chdir(dir),
+        send: (msg) => {
+            process.send?.(msg);
+        },
+    });
+    wireCompileWorkerProcess({
+        on: (event, listener) => process.on(event, listener),
+        exit: code => process.exit(code),
+    }, handler);
+}

package/dist/compile-worker-entry.test.d.ts

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

package/dist/compile-worker-entry.test.d.ts.map

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

package/dist/compile-worker-entry.test.js

@@ -0,0 +1,247 @@
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it, vi } from 'vitest';
+async function getCreateHandler() {
+    const mod = await import('./compile-worker-entry.js').catch(() => null);
+    expect(mod, 'src/compile-worker-entry must exist — it is the child_process.fork() target of the compile worker').not.toBeNull();
+    const fn = mod.createCompileWorkerHandler;
+    expect(typeof fn, 'compile-worker-entry must export createCompileWorkerHandler(deps) so the IPC message handling is unit-testable without forking').toBe('function');
+    return fn;
+}
+const FIXTURE_APP = {
+    appId: 'fixture_app_001',
+    name: 'fixture-app',
+    path: '/tmp/fixture-project',
+};
+const BUILD_MSG = {
+    cmd: 'build',
+    projectPath: '/tmp/fixture-project',
+    outputDir: '/tmp/fixture-out',
+    options: { sourcemap: true },
+};
+function makeDeps(build) {
+    const callOrder = [];
+    const buildSpy = vi.fn((...args) => {
+        callOrder.push('build');
+        return build(...args);
+    });
+    const deps = {
+        loadCompiler: vi.fn(() => buildSpy),
+        chdir: vi.fn((_dir) => {
+            callOrder.push('chdir');
+        }),
+        send: vi.fn((_msg) => { }),
+    };
+    return { deps, buildSpy, callOrder };
+}
+describe('compile-worker-entry — createCompileWorkerHandler (fork-side IPC handler)', () => {
+    it('does NOT load the compiler at handler creation (the fork must stay fast)', async () => {
+        const createHandler = await getCreateHandler();
+        const { deps } = makeDeps(async () => FIXTURE_APP);
+        createHandler(deps);
+        expect(deps.loadCompiler, 'loadCompiler must be deferred to the first build command — requiring @dimina/compiler at fork time defeats the fast long-lived worker').not.toHaveBeenCalled();
+    });
+    it('ignores non-build messages: no compiler load, no reply, no throw', async () => {
+        const createHandler = await getCreateHandler();
+        const { deps } = makeDeps(async () => FIXTURE_APP);
+        const handler = createHandler(deps);
+        await handler(null);
+        await handler('hello');
+        await handler({ cmd: 'shutdown' });
+        await handler({});
+        expect(deps.loadCompiler).not.toHaveBeenCalled();
+        expect(deps.send, 'unknown messages must not produce a reply').not.toHaveBeenCalled();
+    });
+    it('on a build command: chdir(projectPath) in the child BEFORE build, build(outputDir, projectPath, true, options), then send the result', async () => {
+        const createHandler = await getCreateHandler();
+        const { deps, buildSpy, callOrder } = makeDeps(async () => FIXTURE_APP);
+        const handler = createHandler(deps);
+        await handler(BUILD_MSG);
+        expect(deps.chdir).toHaveBeenCalledWith(BUILD_MSG.projectPath);
+        expect(buildSpy).toHaveBeenCalledWith(BUILD_MSG.outputDir, BUILD_MSG.projectPath, true, BUILD_MSG.options);
+        expect(callOrder, 'chdir must happen before build — the compiler resolves project-relative paths off cwd (the whole reason the OLD architecture chdir-ed the host)').toEqual(['chdir', 'build']);
+        expect(deps.send).toHaveBeenCalledTimes(1);
+        expect(deps.send).toHaveBeenCalledWith({ type: 'result', appInfo: FIXTURE_APP });
+    });
+    it('loads the compiler lazily on the FIRST build command and caches it across builds', async () => {
+        const createHandler = await getCreateHandler();
+        const { deps, buildSpy } = makeDeps(async () => FIXTURE_APP);
+        const handler = createHandler(deps);
+        expect(deps.loadCompiler).not.toHaveBeenCalled();
+        await handler(BUILD_MSG);
+        expect(deps.loadCompiler).toHaveBeenCalledTimes(1);
+        await handler(BUILD_MSG);
+        expect(deps.loadCompiler, 'the compiler module must be loaded ONCE per worker lifetime and reused for every subsequent build').toHaveBeenCalledTimes(1);
+        expect(buildSpy).toHaveBeenCalledTimes(2);
+        expect(deps.send).toHaveBeenCalledTimes(2);
+    });
+    it('normalizes a swallowed-error build (undefined return) to { type: "result", appInfo: null }', async () => {
+        const createHandler = await getCreateHandler();
+        // @dimina/compiler build() catches compile errors internally and
+        // resolves undefined (RESULTS.md §① — never rethrows). The protocol
+        // must surface that as an explicit null so the parent keeps its
+        // existing project.config.json fallback path.
+        const { deps } = makeDeps(async () => undefined);
+        const handler = createHandler(deps);
+        await handler(BUILD_MSG);
+        expect(deps.send).toHaveBeenCalledTimes(1);
+        expect(deps.send).toHaveBeenCalledWith(expect.objectContaining({ type: 'result', appInfo: null }));
+    });
+    it('a throwing build still replies ({ appInfo: null, error.message }) and never rejects the handler', async () => {
+        const createHandler = await getCreateHandler();
+        const { deps } = makeDeps(async () => {
+            throw new Error('boom — compiler exploded');
+        });
+        const handler = createHandler(deps);
+        // Must resolve — an unreplied build command would hang the parent's
+        // in-flight rebuild and wedge the rebuild scheduler forever.
+        await expect(handler(BUILD_MSG)).resolves.toBeUndefined();
+        expect(deps.send).toHaveBeenCalledTimes(1);
+        expect(deps.send).toHaveBeenCalledWith(expect.objectContaining({
+            type: 'result',
+            appInfo: null,
+            error: expect.objectContaining({
+                message: expect.stringContaining('boom'),
+            }),
+        }));
+    });
+});
+class FakeWorkerProcess {
+    listeners = new Map();
+    exit = vi.fn((_code) => { });
+    on = vi.fn((event, listener) => {
+        const bucket = this.listeners.get(event) ?? [];
+        bucket.push(listener);
+        this.listeners.set(event, bucket);
+        return this;
+    });
+    emit(event, ...args) {
+        for (const listener of this.listeners.get(event) ?? [])
+            listener(...args);
+    }
+}
+async function getWireWorkerProcess() {
+    const mod = await import('./compile-worker-entry.js').catch(() => null);
+    expect(mod, 'src/compile-worker-entry must exist').not.toBeNull();
+    const fn = mod.wireCompileWorkerProcess;
+    expect(typeof fn, 'compile-worker-entry must export wireCompileWorkerProcess(proc, handler) — the process-lifecycle '
+        + 'wiring (message routing + disconnect self-exit) must be a unit-testable seam, exactly like '
+        + 'createCompileWorkerHandler already is for the message handling').toBe('function');
+    return fn;
+}
+describe('compile-worker-entry — wireCompileWorkerProcess (orphan-safety-net seam)', () => {
+    it('subscribes the disconnect self-exit SYNCHRONOUSLY at wire time, and never exits eagerly', async () => {
+        const wire = await getWireWorkerProcess();
+        const proc = new FakeWorkerProcess();
+        wire(proc, async () => { });
+        expect(proc.listeners.get('disconnect')?.length ?? 0, 'the disconnect listener must be registered synchronously inside wireCompileWorkerProcess — '
+            + 'any async gap is a window where a dying parent orphans the worker').toBeGreaterThanOrEqual(1);
+        expect(proc.exit, 'wiring alone must never exit the process').not.toHaveBeenCalled();
+    });
+    it('on IPC disconnect the worker exits itself with code 0 — the orphan safety net', async () => {
+        const wire = await getWireWorkerProcess();
+        const proc = new FakeWorkerProcess();
+        wire(proc, async () => { });
+        proc.emit('disconnect');
+        expect(proc.exit, 'channel gone ⇒ the worker must kill ITSELF — this covers every parent death that never runs close() '
+            + '(host crash, SIGKILL, teardown race)').toHaveBeenCalledWith(0);
+    });
+    it('routes every inbound IPC message to the provided handler (the forked path and the unit-tested path stay one code path)', async () => {
+        const wire = await getWireWorkerProcess();
+        const proc = new FakeWorkerProcess();
+        const handled = [];
+        wire(proc, async (msg) => {
+            handled.push(msg);
+        });
+        proc.emit('message', BUILD_MSG);
+        proc.emit('message', { cmd: 'noop' });
+        expect(handled).toEqual([BUILD_MSG, { cmd: 'noop' }]);
+        expect(proc.exit, 'message traffic must never exit the worker').not.toHaveBeenCalled();
+    });
+});
+/**
+ * CODEX-REVIEW REGRESSION (m9) — the fork-mode self-wiring gate currently
+ * uses `process.argv[1].includes('compile-worker-entry')`, a SUBSTRING match.
+ * Any unrelated script whose path merely contains that fragment (run with an
+ * IPC channel, e.g. itself a fork) would import this module and silently
+ * self-wire: a disconnect→exit(0) handler and a message handler hijacking the
+ * host's IPC traffic. The gate must engage ONLY when argv[1] is THIS module
+ * (same path as import.meta.url) — pinned behaviorally below via a fresh
+ * module evaluation under a manipulated argv[1].
+ *
+ * Observation seam: self-wiring is `process.on('message'|'disconnect', …)` on
+ * the REAL process — the tests diff the process listener sets around the
+ * import and remove any added listeners again in cleanup (so a failing run
+ * can never leak a disconnect→exit(0) handler into the vitest worker).
+ */
+describe('compile-worker-entry — fork-mode self-wiring gate (codex m9)', () => {
+    function snapshotListeners() {
+        return {
+            message: process.listeners('message'),
+            disconnect: process.listeners('disconnect'),
+        };
+    }
+    function addedSince(before) {
+        const current = snapshotListeners();
+        return {
+            message: current.message.filter(listener => !before.message.includes(listener)),
+            disconnect: current.disconnect.filter(listener => !before.disconnect.includes(listener)),
+        };
+    }
+    function removeListeners(added) {
+        for (const listener of added.message)
+            process.removeListener('message', listener);
+        for (const listener of added.disconnect)
+            process.removeListener('disconnect', listener);
+    }
+    async function importEntryFreshWithArgv1(argv1) {
+        process.argv[1] = argv1;
+        vi.resetModules();
+        await import('./compile-worker-entry.js');
+    }
+    it('m9: an argv[1] LOOKALIKE path (substring match) must NOT self-wire the worker IPC handlers', async () => {
+        const originalArgv1 = process.argv[1] ?? '';
+        const originalSend = process.send;
+        const before = snapshotListeners();
+        try {
+            // An IPC channel is present (vitest forks pool) or stubbed — the
+            // substring gate is the only thing standing between this unrelated
+            // script path and a hijacked process.
+            if (typeof process.send !== 'function') {
+                process.send = (() => true);
+            }
+            await importEntryFreshWithArgv1('/tmp/my-compile-worker-entry-lookalike.js');
+            const added = addedSince(before);
+            expect(added.disconnect, 'argv[1] = /tmp/my-compile-worker-entry-lookalike.js is NOT this module — a substring gate self-wires '
+                + 'a disconnect→exit(0) handler into the unsuspecting host process').toHaveLength(0);
+            expect(added.message, 'the lookalike path must not get a message handler either — it would intercept the host\'s own IPC traffic').toHaveLength(0);
+        }
+        finally {
+            removeListeners(addedSince(before));
+            process.argv[1] = originalArgv1;
+            process.send = originalSend;
+            vi.resetModules();
+        }
+    });
+    it('m9 positive control: when argv[1] IS this entry module, the fork-mode self-wiring engages', async () => {
+        const originalArgv1 = process.argv[1] ?? '';
+        const originalSend = process.send;
+        const before = snapshotListeners();
+        try {
+            if (typeof process.send !== 'function') {
+                process.send = (() => true);
+            }
+            const entryPath = fileURLToPath(new URL('./compile-worker-entry.ts', import.meta.url));
+            await importEntryFreshWithArgv1(entryPath);
+            const added = addedSince(before);
+            expect(added.disconnect.length, 'with argv[1] pointing at THIS module the self-wiring must engage (disconnect orphan safety net) — '
+                + 'a fix that simply disables the gate would orphan every real fork').toBeGreaterThanOrEqual(1);
+            expect(added.message.length, 'the real fork path must wire the message handler').toBeGreaterThanOrEqual(1);
+        }
+        finally {
+            removeListeners(addedSince(before));
+            process.argv[1] = originalArgv1;
+            process.send = originalSend;
+            vi.resetModules();
+        }
+    });
+});

package/dist/compile-worker-leak.test.d.ts

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