@dimina-kit/devkit 0.1.2-dev.20260703051110 → 0.1.2-dev.20260706064107

package/README.md

@@ -59,6 +59,22 @@ await session.close()
 | `port`    | `number`              | 实际监听的端口                      |
 | `close`   | `() => Promise<void>` | 关闭文件监听和预览服务器            |
 
+### enableCompileWorkerStandby（热备胎，可选加速器）
+
+进程级开关：预先 fork 一个**项目无关**的编译子进程并预热编译器（不 chdir、不编译任何项目），之后每次 `openProject` 自动领养它——首编省掉 fork + 编译器加载（实测 ~1.6s）；每次 `session.close()` 后自动补一个新备胎。**纯加速器**：备胎的任何失效（悄悄死亡、健康检查失败、崩溃熔断）都自动退化为原有的冷 fork 路径，绝不影响 openProject 的成败。
+
+```typescript
+import { enableCompileWorkerStandby } from '@dimina-kit/devkit'
+
+const standby = enableCompileWorkerStandby({
+  onEvent: ev => console.log('[standby]', ev.type, ev.pid ?? '', ev.reason ?? ''),
+})
+// …应用退出时：
+await standby.dispose() // 杀掉备胎；之后 openProject 永远走冷路径，不再补胎
+```
+
+稳定性设计（面向发布到用户机器）：领养前 ping/pong 健康检查（默认 1s 超时，卡死的备胎会被杀掉而不是交出去）；意外死亡自动补胎，但 30 秒内连死 3 次触发熔断（`degraded`，本次会话内永久停用，防 fork 风暴）；`onEvent` 暴露完整生命周期（`spawned` / `prewarmed` / `adopted` / `health-check-failed` / `died` / `degraded`）供接入诊断。未调用此 API 时行为与之前完全一致。
+
 ---
 
 ## 工作流程

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

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

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

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

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

@@ -0,0 +1,187 @@
+import { execFileSync, fork } from 'node:child_process';
+import { once } from 'node:events';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { afterEach, describe, expect, it } from 'vitest';
+import { createCompileWorker } from './compile-worker.js';
+/**
+ * Contract for warm-standby ADOPTION on the `createCompileWorker` side:
+ * `opts.adopt?: ChildProcess` lets a caller (devtools' warm-standby manager)
+ * hand over an already-forked, already-toolchain-warmed compile worker so
+ * the FIRST build of a newly opened project reuses it instead of paying a
+ * fresh fork + `@dimina-kit/compiler` import.
+ *
+ * REAL-fork, real-compile integration tests (same style as
+ * `compile-worker-leak.test.ts`): the adopted process is a genuine fork of
+ * `compile-worker-entry`, and "reused, not re-forked" is proven by a real OS
+ * PID scan — `ps -axo pid=,ppid=,command=` for direct children of THIS test
+ * process whose command line names the entry module — not by a spy.
+ */
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+function workerEntryPath() {
+    const js = path.join(__dirname, 'compile-worker-entry.js');
+    if (fs.existsSync(js))
+        return js;
+    return path.join(__dirname, 'compile-worker-entry.ts');
+}
+function workerExecArgv(entry) {
+    return entry.endsWith('.ts')
+        ? ['--experimental-strip-types', '--disable-warning=ExperimentalWarning']
+        : [];
+}
+function sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+function pidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function waitForPidDeath(pid, timeoutMs = 8000) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        if (!pidAlive(pid))
+            return true;
+        await sleep(100);
+    }
+    return !pidAlive(pid);
+}
+async function waitForPidAlive(pid, timeoutMs = 8000) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        if (pidAlive(pid))
+            return true;
+        await sleep(100);
+    }
+    return pidAlive(pid);
+}
+/** Direct children of THIS test process that are compile-worker-entry forks. */
+function findCompileWorkerPids() {
+    const out = execFileSync('ps', ['-axo', 'pid=,ppid=,command='], { encoding: 'utf8' });
+    const pids = [];
+    for (const line of out.split('\n')) {
+        const match = line.trim().match(/^(\d+)\s+(\d+)\s+(.*)$/);
+        if (!match)
+            continue;
+        const [, pid, ppid, command] = match;
+        if (Number(ppid) !== process.pid)
+            continue;
+        if (!command.includes('compile-worker-entry'))
+            continue;
+        pids.push(Number(pid));
+    }
+    return pids;
+}
+function forkAdoptCandidate() {
+    const entry = workerEntryPath();
+    // Same fork shape createCompileWorker's own spawnWorker uses: piped stdio +
+    // an explicit execArgv (never the parent's loaders) so the adopted process
+    // is indistinguishable from one createCompileWorker would have forked itself.
+    return fork(entry, [], { execArgv: workerExecArgv(entry), silent: true });
+}
+const doomedPids = [];
+const cleanupRoots = [];
+const activeWorkers = [];
+afterEach(async () => {
+    for (const worker of activeWorkers.splice(0)) {
+        try {
+            await worker.close();
+        }
+        catch {
+            // best-effort teardown
+        }
+    }
+    for (const pid of doomedPids.splice(0)) {
+        if (pidAlive(pid)) {
+            try {
+                process.kill(pid, 'SIGKILL');
+            }
+            catch {
+                // already gone
+            }
+        }
+    }
+    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-adopt-'));
+    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', '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;
+}
+describe('createCompileWorker — opts.adopt (warm-standby hand-off)', () => {
+    it('the FIRST build reuses the adopted process (same PID, no extra fork), pipes its stdout to onLog, and close() kills that same PID', async () => {
+        const adoptee = forkAdoptCandidate();
+        await once(adoptee, 'spawn');
+        doomedPids.push(adoptee.pid);
+        expect(pidAlive(adoptee.pid)).toBe(true);
+        const logEntries = [];
+        const worker = createCompileWorker({
+            onLog: entry => logEntries.push(entry),
+            adopt: adoptee,
+        });
+        activeWorkers.push(worker);
+        const root = makeFixture();
+        const appInfo = await worker.build({
+            projectPath: root,
+            outputDir: path.join(root, '.out'),
+            options: {},
+        });
+        expect(appInfo?.appId).toBe('fixture_app_001');
+        const liveWorkerPids = findCompileWorkerPids();
+        expect(liveWorkerPids, 'the first build must reuse the ADOPTED process, not fork a fresh one — exactly one compile-worker-entry child must exist, and it must be the adoptee').toEqual([adoptee.pid]);
+        expect(logEntries.length, 'the adopted process\'s stdout/stderr must flow to onLog just like a self-forked worker\'s').toBeGreaterThan(0);
+        await worker.close();
+        expect(await waitForPidDeath(adoptee.pid, 8000), 'close() on a worker using an adopted process must leave that PID actually dead — same guarantee as a self-forked worker').toBe(true);
+    }, 90_000);
+    it('an adopted process that dies BEFORE the first build falls back to a fresh fork, and the build still succeeds', async () => {
+        const adoptee = forkAdoptCandidate();
+        await once(adoptee, 'spawn');
+        const deadPid = adoptee.pid;
+        adoptee.kill('SIGKILL');
+        expect(await waitForPidDeath(deadPid, 8000)).toBe(true);
+        const worker = createCompileWorker({
+            adopt: adoptee,
+        });
+        activeWorkers.push(worker);
+        const root = makeFixture();
+        const appInfo = await worker.build({
+            projectPath: root,
+            outputDir: path.join(root, '.out'),
+            options: {},
+        });
+        expect(appInfo?.appId, 'a dead adoptee must not fail the build — createCompileWorker must transparently fork a FRESH worker instead').toBe('fixture_app_001');
+        const liveWorkerPids = findCompileWorkerPids();
+        expect(liveWorkerPids).toHaveLength(1);
+        expect(liveWorkerPids[0], 'the fallback fork must be a genuinely NEW process, not the dead adoptee').not.toBe(deadPid);
+        doomedPids.push(liveWorkerPids[0]);
+        await worker.close();
+    }, 90_000);
+    it('a fresh (never-crashed) adopted process is genuinely alive at hand-off time — precondition sanity check', async () => {
+        const adoptee = forkAdoptCandidate();
+        await once(adoptee, 'spawn');
+        doomedPids.push(adoptee.pid);
+        expect(await waitForPidAlive(adoptee.pid, 3000)).toBe(true);
+        adoptee.kill('SIGKILL');
+    });
+});

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

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

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

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

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

@@ -0,0 +1,110 @@
+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').not.toBeNull();
+    const fn = mod.createCompileWorkerHandler;
+    expect(typeof fn, 'compile-worker-entry must export createCompileWorkerHandler(deps)').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, warmPool) {
+    const buildSpy = vi.fn((...args) => build(...args));
+    const loadCompilerSpy = vi.fn(() => buildSpy);
+    const deps = {
+        loadCompiler: loadCompilerSpy,
+        chdir: vi.fn((_dir) => { }),
+        send: vi.fn((_msg) => { }),
+        ...(warmPool ? { warmPool: vi.fn(warmPool) } : {}),
+    };
+    return { deps, buildSpy, loadCompilerSpy };
+}
+describe('compile-worker-entry — ping/prewarm (warm-standby protocol extension)', () => {
+    it('ping replies pong synchronously and NEVER triggers loadCompiler', async () => {
+        const createHandler = await getCreateHandler();
+        const { deps, loadCompilerSpy } = makeDeps(async () => FIXTURE_APP);
+        const handler = createHandler(deps);
+        await handler({ cmd: 'ping', id: 'p1' });
+        expect(loadCompilerSpy, 'a ping health check must never load the compiler — a spare must be pingable while cold-idle').not.toHaveBeenCalled();
+        expect(deps.send).toHaveBeenCalledTimes(1);
+        expect(deps.send).toHaveBeenCalledWith({ type: 'pong', id: 'p1' });
+    });
+    it('prewarm loads the compiler, calls warmPool if provided, and replies prewarm-result ok:true', async () => {
+        const createHandler = await getCreateHandler();
+        const warmPool = vi.fn(async () => { });
+        const { deps, loadCompilerSpy } = makeDeps(async () => FIXTURE_APP, warmPool);
+        const handler = createHandler(deps);
+        await handler({ cmd: 'prewarm', id: 'w1' });
+        expect(loadCompilerSpy).toHaveBeenCalledTimes(1);
+        expect(deps.warmPool, 'when warmPool is provided, prewarm must await it (after loadCompiler)').toHaveBeenCalledTimes(1);
+        expect(deps.send).toHaveBeenCalledWith({ type: 'prewarm-result', id: 'w1', ok: true });
+    });
+    it('a build AFTER a successful prewarm reuses the SAME cached compiler — loadCompiler is called exactly once total', async () => {
+        const createHandler = await getCreateHandler();
+        const { deps, buildSpy, loadCompilerSpy } = makeDeps(async () => FIXTURE_APP);
+        const handler = createHandler(deps);
+        await handler({ cmd: 'prewarm', id: 'w1' });
+        await handler(BUILD_MSG);
+        expect(loadCompilerSpy, 'prewarm and the first build must share ONE compiler load/cache — a prewarmed spare that reloads on its first real build wastes the whole point of prewarming').toHaveBeenCalledTimes(1);
+        expect(buildSpy).toHaveBeenCalledTimes(1);
+        expect(deps.send).toHaveBeenCalledTimes(2);
+        expect(deps.send).toHaveBeenLastCalledWith(expect.objectContaining({ type: 'result', appInfo: FIXTURE_APP }));
+    });
+    it('prewarm works without a warmPool dependency (it is OPTIONAL) — no crash, ok:true', async () => {
+        const createHandler = await getCreateHandler();
+        const { deps } = makeDeps(async () => FIXTURE_APP);
+        const handler = createHandler(deps);
+        await expect(handler({ cmd: 'prewarm', id: 'w2' })).resolves.toBeUndefined();
+        expect(deps.send).toHaveBeenCalledWith({ type: 'prewarm-result', id: 'w2', ok: true });
+    });
+    it('prewarm replies ok:false with the error message when loadCompiler throws — the handler itself still resolves', async () => {
+        const createHandler = await getCreateHandler();
+        const failingLoad = vi.fn(() => {
+            throw new Error('boom — toolchain load failed');
+        });
+        const deps = {
+            loadCompiler: failingLoad,
+            chdir: vi.fn(),
+            send: vi.fn(),
+        };
+        const handler = createHandler(deps);
+        await expect(handler({ cmd: 'prewarm', id: 'w3' })).resolves.toBeUndefined();
+        expect(deps.send).toHaveBeenCalledWith(expect.objectContaining({
+            type: 'prewarm-result',
+            id: 'w3',
+            ok: false,
+            error: expect.stringContaining('boom'),
+        }));
+    });
+    it('prewarm replies ok:false with the error message when warmPool rejects — the handler itself still resolves', async () => {
+        const createHandler = await getCreateHandler();
+        const warmPool = vi.fn(async () => {
+            throw new Error('boom — pool warm-up failed');
+        });
+        const { deps } = makeDeps(async () => FIXTURE_APP, warmPool);
+        const handler = createHandler(deps);
+        await expect(handler({ cmd: 'prewarm', id: 'w4' })).resolves.toBeUndefined();
+        expect(deps.send).toHaveBeenCalledWith(expect.objectContaining({
+            type: 'prewarm-result',
+            id: 'w4',
+            ok: false,
+            error: expect.stringContaining('boom'),
+        }));
+    });
+    it('prewarm NEVER calls chdir — the whole safety of a project-agnostic spare rests on this', async () => {
+        const createHandler = await getCreateHandler();
+        const { deps } = makeDeps(async () => FIXTURE_APP, async () => { });
+        const handler = createHandler(deps);
+        await handler({ cmd: 'prewarm', id: 'w5' });
+        expect(deps.chdir, 'prewarm must be project-agnostic: chdir-ing during prewarm would tie the spare to whatever project happened to be current at fork time').not.toHaveBeenCalled();
+    });
+});

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

@@ -20,25 +20,55 @@ export interface WorkerResultMessage {
         message: string;
     };
 }
+/** Reply to `{ cmd: 'ping' }` — the warm-standby manager's health probe. */
+export interface WorkerPongMessage {
+    type: 'pong';
+    id: string;
+}
+/** Reply to `{ cmd: 'prewarm' }` — ok:false carries the load/warm failure. */
+export interface WorkerPrewarmResultMessage {
+    type: 'prewarm-result';
+    id: string;
+    ok: boolean;
+    error?: string;
+}
+export type WorkerOutboundMessage = WorkerResultMessage | WorkerPongMessage | WorkerPrewarmResultMessage;
 export interface CompileWorkerHandlerDeps {
     /**
-     * Lazy compiler load — deferred to the first build. May be sync (a plain
-     * `require`) or async (a dynamic `import()` of the ESM `@dimina-kit/compiler`
-     * pool); the handler awaits it either way. Loaded ONCE and cached.
+     * Lazy compiler load — deferred to the first build (or an explicit prewarm).
+     * May be sync (a plain `require`) or async (a dynamic `import()` of the ESM
+     * `@dimina-kit/compiler` pool); the handler awaits it either way. Loaded
+     * ONCE and cached — a build after a prewarm reuses the prewarmed load.
      */
     loadCompiler: () => WorkerBuildFn | Promise<WorkerBuildFn>;
     /** `process.chdir` — mutates the CHILD process cwd only. */
     chdir: (dir: string) => void;
     /** `process.send` — replies to the parent. */
-    send: (msg: WorkerResultMessage) => void;
+    send: (msg: WorkerOutboundMessage) => void;
+    /**
+     * Optional deep warm-up run by `{ cmd: 'prewarm' }` after the compiler
+     * loads (e.g. spinning up the resident pool's stage workers so the first
+     * real build starts on warm threads). Project-agnostic by contract.
+     */
+    warmPool?: () => Promise<void>;
 }
 /**
- * Build the fork-side IPC message handler. Non-build messages are ignored
+ * Build the fork-side IPC message handler. Unknown 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.
+ *
+ * Two warm-standby commands ride the same channel:
+ *  - `{ cmd: 'ping', id }` → `{ type: 'pong', id }`. Pure liveness; never
+ *    loads the compiler (a health check on a cold-idle spare must stay cheap).
+ *  - `{ cmd: 'prewarm', id }` → loads the compiler into the SAME cache the
+ *    build path uses, then awaits `deps.warmPool?.()`, and always replies
+ *    `{ type: 'prewarm-result', id, ok, error? }` (a failed prewarm reports —
+ *    it never throws out of the handler). Deliberately NO chdir: a prewarmed
+ *    spare stays project-agnostic, which is what makes adopting it into ANY
+ *    next-opened project safe.
  */
 export declare function createCompileWorkerHandler(deps: CompileWorkerHandlerDeps): (msg: unknown) => Promise<void>;
 /**

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

@@ -1 +1 @@
-{"version":3,"file":"compile-worker-entry.d.ts","sourceRoot":"","sources":["../src/compile-worker-entry.ts"],"names":[],"mappings":"AAiBA,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;IACnB,gFAAgF;IAChF,SAAS,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,CAAA;CAC5E;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;;;;OAIG;IACH,YAAY,EAAE,MAAM,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC,CAAA;IAC1D,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"}
+{"version":3,"file":"compile-worker-entry.d.ts","sourceRoot":"","sources":["../src/compile-worker-entry.ts"],"names":[],"mappings":"AAiBA,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;IACnB,gFAAgF;IAChF,SAAS,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,CAAA;CAC5E;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,4EAA4E;AAC5E,MAAM,WAAW,iBAAiB;IACjC,IAAI,EAAE,MAAM,CAAA;IACZ,EAAE,EAAE,MAAM,CAAA;CACV;AAED,8EAA8E;AAC9E,MAAM,WAAW,0BAA0B;IAC1C,IAAI,EAAE,gBAAgB,CAAA;IACtB,EAAE,EAAE,MAAM,CAAA;IACV,EAAE,EAAE,OAAO,CAAA;IACX,KAAK,CAAC,EAAE,MAAM,CAAA;CACd;AAED,MAAM,MAAM,qBAAqB,GAC9B,mBAAmB,GAAG,iBAAiB,GAAG,0BAA0B,CAAA;AAEvE,MAAM,WAAW,wBAAwB;IACxC;;;;;OAKG;IACH,YAAY,EAAE,MAAM,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC,CAAA;IAC1D,4DAA4D;IAC5D,KAAK,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAA;IAC5B,8CAA8C;IAC9C,IAAI,EAAE,CAAC,GAAG,EAAE,qBAAqB,KAAK,IAAI,CAAA;IAC1C;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;CAC9B;AA0BD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,0BAA0B,CACzC,IAAI,EAAE,wBAAwB,GAC5B,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC,IAAI,CAAC,CA4CjC;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

@@ -19,17 +19,54 @@ function isBuildMessage(msg) {
         && msg !== null
         && msg.cmd === 'build');
 }
+function isCommandWithId(msg, cmd) {
+    return (typeof msg === 'object'
+        && msg !== null
+        && msg.cmd === cmd
+        && typeof msg.id === 'string');
+}
 /**
- * Build the fork-side IPC message handler. Non-build messages are ignored
+ * Build the fork-side IPC message handler. Unknown 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.
+ *
+ * Two warm-standby commands ride the same channel:
+ *  - `{ cmd: 'ping', id }` → `{ type: 'pong', id }`. Pure liveness; never
+ *    loads the compiler (a health check on a cold-idle spare must stay cheap).
+ *  - `{ cmd: 'prewarm', id }` → loads the compiler into the SAME cache the
+ *    build path uses, then awaits `deps.warmPool?.()`, and always replies
+ *    `{ type: 'prewarm-result', id, ok, error? }` (a failed prewarm reports —
+ *    it never throws out of the handler). Deliberately NO chdir: a prewarmed
+ *    spare stays project-agnostic, which is what makes adopting it into ANY
+ *    next-opened project safe.
  */
 export function createCompileWorkerHandler(deps) {
     let cachedBuild = null;
     return async (msg) => {
+        if (isCommandWithId(msg, 'ping')) {
+            deps.send({ type: 'pong', id: msg.id });
+            return;
+        }
+        if (isCommandWithId(msg, 'prewarm')) {
+            try {
+                if (!cachedBuild)
+                    cachedBuild = await deps.loadCompiler();
+                await deps.warmPool?.();
+                deps.send({ type: 'prewarm-result', id: msg.id, ok: true });
+            }
+            catch (err) {
+                deps.send({
+                    type: 'prewarm-result',
+                    id: msg.id,
+                    ok: false,
+                    error: err instanceof Error ? err.message : String(err),
+                });
+            }
+            return;
+        }
         if (!isBuildMessage(msg))
             return;
         try {
@@ -107,6 +144,13 @@ if (isForkedWorkerEntry) {
         // workers WARM across rebuilds). ESM package → dynamic import (works on Node 20+);
         // its default export is the pooled build fn.
         loadCompiler: async () => (await import('@dimina-kit/compiler/pool-node')).default,
+        // Deep prewarm for the warm-standby spare: spin up the resident pool's stage
+        // workers ahead of the first build. Optional-chained so an older compiler
+        // package without the export degrades to load-only prewarm.
+        warmPool: async () => {
+            const pool = await import('@dimina-kit/compiler/pool-node');
+            await pool.warmDefaultPool?.();
+        },
         chdir: dir => process.chdir(dir),
         send: (msg) => {
             process.send?.(msg);

package/dist/compile-worker-standby-hardening.test.d.ts

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

package/dist/compile-worker-standby-hardening.test.d.ts.map

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