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

package/dist/index.d.ts

@@ -41,6 +41,14 @@ export interface OpenProjectOptions {
      * worker's piped stdout/stderr, tagged with their source stream.
      */
     onLog?: (entry: CompileLogEntry) => void;
+    /**
+     * Fired when the file watcher emits `'error'` (EMFILE, permission loss, …)
+     * AFTER its initial scan already resolved `ready` — i.e. the session is
+     * live and auto-rebuild-on-save has silently stopped working. A pre-ready
+     * error instead rejects `openProject` itself (see `createProjectWatcher`),
+     * so this only ever fires once per session, at most.
+     */
+    onWatcherError?: (err: unknown) => void;
 }
 export declare function openProject(opts: OpenProjectOptions): Promise<ProjectSession>;
 /**
@@ -49,7 +57,7 @@ export declare function openProject(opts: OpenProjectOptions): Promise<ProjectSe
  * 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>): {
+export declare function createProjectWatcher(projectPath: string, onChange: () => void | Promise<void>, onWatcherError?: (err: unknown) => void): {
     close: () => Promise<void>;
     ready: Promise<void>;
 };

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAgB,eAAe,EAAiB,MAAM,qBAAqB,CAAA;AAEvF,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;;;;OAIG;IACH,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;IAC5E,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;AAuFD,wBAAsB,WAAW,CAAC,IAAI,EAAE,kBAAkB,GAAG,OAAO,CAAC,cAAc,CAAC,CAqInF;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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAgB,eAAe,EAAiB,MAAM,qBAAqB,CAAA;AAEvF,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;;;;OAIG;IACH,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;IAC5E,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;IACxC;;;;;;OAMG;IACH,cAAc,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,IAAI,CAAA;CACvC;AAuFD,wBAAsB,WAAW,CAAC,IAAI,EAAE,kBAAkB,GAAG,OAAO,CAAC,cAAc,CAAC,CAwInF;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CACnC,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,EACpC,cAAc,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,IAAI,GACrC;IAAE,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAAC,KAAK,EAAE,OAAO,CAAC,IAAI,CAAC,CAAA;CAAE,CA2DtD"}

package/dist/index.js

@@ -114,7 +114,7 @@ async function cleanupFailedOpen(watcher, compileWorker, server) {
     }
 }
 export async function openProject(opts) {
-    const { projectPath: rawProjectPath, port = 0, sourcemap = false, fileTypes, simulatorDir, containerDir: overrideContainerDir, outputDir, watch = true, onRebuild, onBuildError, onLog, } = opts;
+    const { projectPath: rawProjectPath, port = 0, sourcemap = false, fileTypes, simulatorDir, containerDir: overrideContainerDir, outputDir, watch = true, onRebuild, onBuildError, onLog, onWatcherError, } = opts;
     const projectPath = path.resolve(rawProjectPath);
     const buildOptions = { sourcemap, fileTypes };
     const resolvedPort = port === 0 ? await getRandomPort() : port;
@@ -194,7 +194,9 @@ export async function openProject(opts) {
         // a build is in flight is never dropped: it coalesces into exactly one
         // trailing rebuild once the current run settles.
         const rebuildScheduler = createRebuildScheduler(() => runRebuild(compileWorker, buildRequest, sessionApps, () => reload, onRebuild, onBuildError));
-        watcher = watch ? createProjectWatcher(projectPath, () => rebuildScheduler.schedule()) : null;
+        watcher = watch
+            ? createProjectWatcher(projectPath, () => rebuildScheduler.schedule(), onWatcherError)
+            : 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
@@ -232,7 +234,7 @@ export async function openProject(opts) {
  * 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) {
+export function createProjectWatcher(projectPath, onChange, onWatcherError) {
     // Ignore dotfiles/dot-directories that live *inside* the project (.git,
     // .DS_Store, editor scratch, etc.) without nuking the whole watch when the
     // project itself sits under a dotted ancestor path. A regex like
@@ -267,12 +269,24 @@ export function createProjectWatcher(projectPath, 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.
+    // listener also doubles as the EventEmitter unhandled-'error' guard. Once
+    // `ready` has settled, the reject above is a no-op — that's the live-session
+    // case (watcher died mid-session, not at open time) and is instead surfaced
+    // through `onWatcherError`, the only remaining signal that auto-rebuild has
+    // silently stopped.
+    let readySettled = false;
     const ready = new Promise((resolve, reject) => {
-        watcher.once('ready', () => resolve());
+        watcher.once('ready', () => {
+            readySettled = true;
+            resolve();
+        });
         watcher.on('error', (err) => {
-            reject(err instanceof Error ? err : new Error(String(err)));
+            if (!readySettled) {
+                readySettled = true;
+                reject(err instanceof Error ? err : new Error(String(err)));
+                return;
+            }
+            onWatcherError?.(err);
         });
     });
     return {

package/dist/open-project-watcher-error-callback.test.d.ts

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

package/dist/open-project-watcher-error-callback.test.d.ts.map

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

package/dist/open-project-watcher-error-callback.test.js

@@ -0,0 +1,191 @@
+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';
+/**
+ * Contract: `openProject` gains an `onWatcherError?: (err: unknown) => void`
+ * option. A watcher 'error' BEFORE the initial scan completes must keep
+ * rejecting `openProject` exactly as today (see open-project-cleanup.test.ts)
+ * — `onWatcherError` must NOT be called for that pre-ready path, so callers
+ * don't get a double signal for the same failure.
+ *
+ * A watcher 'error' AFTER 'ready' (EMFILE, permission loss mid-session, …) is
+ * TODAY silently dropped: `createProjectWatcher`'s `watcher.on('error', ...)`
+ * only rejects the (long-since-settled) `ready` promise, a no-op once ready
+ * has already resolved. The project keeps "running" with a dead watcher and
+ * nothing downstream ever finds out — a save after that point compiles
+ * nothing, forever, with no diagnostic. The fix: `openProject` must forward a
+ * post-ready watcher 'error' to `onWatcherError` so a caller (devtools'
+ * workspace-service) can surface "auto-rebuild stopped working" instead of
+ * silently going stale.
+ *
+ * Harness: verbatim copy of open-project-cleanup.test.ts's fake-fork +
+ * fake-watcher setup (fork/fe/chokidar all mocked so the failure point is
+ * injectable), plus a FakeWatcher that can fire 'error' AFTER 'ready'.
+ */
+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 } };
+});
+vi.mock('../fe/index.js', () => ({ start: mocks.feStart }));
+vi.mock('chokidar', () => ({
+    default: { watch: mocks.watch },
+    watch: mocks.watch,
+}));
+class FakeChild extends EventEmitter {
+    stdout = new PassThrough();
+    stderr = new PassThrough();
+    connected = true;
+    pid = 4343;
+    send = vi.fn((msg) => {
+        const m = msg;
+        if (m && m.cmd === 'build') {
+            queueMicrotask(() => {
+                if (!this.connected)
+                    return;
+                this.emit('message', {
+                    type: 'result',
+                    appInfo: { appId: 'watcher_err_app_001', name: 'watcher-err-app', path: String(m.projectPath ?? '') },
+                });
+            });
+        }
+        return true;
+    });
+    kill = vi.fn(() => {
+        this.connected = false;
+        queueMicrotask(() => this.emit('exit', null, 'SIGTERM'));
+        return true;
+    });
+}
+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();
+});
+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-watcher-err-'));
+    cleanupRoots.push(root);
+    fs.writeFileSync(path.join(root, 'project.config.json'), JSON.stringify({ appid: 'watcher_err_app_001', projectname: 'watcher-err-app' }));
+    return root;
+}
+function sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+describe('openProject onWatcherError — post-ready watcher errors are surfaced, pre-ready path is unchanged', () => {
+    it('does NOT call onWatcherError for a watcher error BEFORE ready (openProject still rejects, same as today)', async () => {
+        const root = makeFixture();
+        mocks.watch.mockImplementation(() => {
+            const watcher = new FakeWatcher();
+            watchers.push(watcher);
+            setTimeout(() => {
+                try {
+                    watcher.emit('error', new Error('EMFILE: too many open files, watch'));
+                }
+                catch {
+                    // no 'error' listener path — matches open-project-cleanup.test.ts
+                }
+            }, 10);
+            return watcher;
+        });
+        const onWatcherError = vi.fn();
+        await expect(devkit.openProject({
+            projectPath: root,
+            watch: true,
+            outputDir: path.join(root, '.out'),
+            onWatcherError,
+        })).rejects.toThrow();
+        expect(onWatcherError, 'a pre-ready watcher error must keep rejecting openProject WITHOUT also invoking onWatcherError — '
+            + 'the caller already gets the failure via the rejected promise').not.toHaveBeenCalled();
+    }, 15_000);
+    it('calls onWatcherError with the error when the watcher fails AFTER ready — openProject has already resolved by then', async () => {
+        const root = makeFixture();
+        let capturedWatcher = null;
+        mocks.watch.mockImplementation(() => {
+            const watcher = new FakeWatcher();
+            watchers.push(watcher);
+            capturedWatcher = watcher;
+            queueMicrotask(() => watcher.emit('ready'));
+            return watcher;
+        });
+        const onWatcherError = vi.fn();
+        const session = await devkit.openProject({
+            projectPath: root,
+            watch: true,
+            outputDir: path.join(root, '.out'),
+            onWatcherError,
+        });
+        const postReadyError = new Error('EMFILE: too many open files, watch (post-ready)');
+        capturedWatcher.emit('error', postReadyError);
+        await sleep(20);
+        expect(onWatcherError, 'today nothing listens for a post-ready watcher error beyond the already-settled ready promise — '
+            + 'the project silently stops auto-rebuilding forever with no signal').toHaveBeenCalledWith(postReadyError);
+        await session.close();
+    }, 15_000);
+    it('a post-ready watcher error does not crash the process (no unhandled "error" event) even without onWatcherError supplied', async () => {
+        const root = makeFixture();
+        let capturedWatcher = null;
+        mocks.watch.mockImplementation(() => {
+            const watcher = new FakeWatcher();
+            watchers.push(watcher);
+            capturedWatcher = watcher;
+            queueMicrotask(() => watcher.emit('ready'));
+            return watcher;
+        });
+        const session = await devkit.openProject({
+            projectPath: root,
+            watch: true,
+            outputDir: path.join(root, '.out'),
+        });
+        expect(() => {
+            capturedWatcher.emit('error', new Error('EMFILE (no onWatcherError supplied)'));
+        }).not.toThrow();
+        await session.close();
+    }, 15_000);
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dimina-kit/devkit",
-  "version": "0.1.2-dev.20260703051110",
+  "version": "0.1.2-dev.20260703101348",
   "description": "Development toolkit for Dimina mini-apps with H5 container preview",
   "keywords": [
     "dimina",
@@ -62,7 +62,7 @@
     "cors": "^2.8.6",
     "express": "^5.2.1",
     "open": "^11.0.0",
-    "@dimina-kit/compiler": "0.0.1-dev.20260703051110"
+    "@dimina-kit/compiler": "0.0.1-dev.20260703101348"
   },
   "publishConfig": {
     "access": "public"