poveste 0.8.2 → 0.10.0

package/dist/node/bin.js

@@ -13,21 +13,52 @@ process.env.POVESTE = 'true';
 // and take it away, which Vike does — and a failed build then ran forever with
 // its error already printed (#405).
 //
-// So failure is reported and exited here, deliberately. `exitCode` alone is not
-// enough — teardown does not get every handle back, and after a failed build a
-// `Timeout` and three `MessagePort`s are still open, so waiting for an empty
-// event loop is what hung in the first place. But exiting on the same tick as
-// the error would truncate it: writes to a piped stderr are asynchronous, and a
-// framed compiler error is long.
+// So failure is reported here, the exit code set, and the process forced out if
+// it does not leave on its own. Closing the collection ports (#426) was not
+// enough on its own: a failed build still hangs in the nuxt4 and sveltekit books,
+// holding `FSEventWrap` and `FSReqCallback` handles — watchers nothing closes on
+// the error path. And `dev` and `preview` hold a listening server by design, so
+// for them no amount of leak-fixing would ever let the loop drain.
 //
-// So both: the exit code is set immediately, and the hard exit is a timer that
-// does not itself hold the loop open. A process with nothing leaked exits on its
-// own, flushing normally; one that leaked is cut loose a moment later, by which
-// time the error has been written.
+// The timer is unref'd, so it never fires for a process that ends by itself and
+// costs nothing when there is nothing to force. It is 500ms rather than
+// immediate because exiting on the same tick as `console.error` truncates it:
+// writes to a piped stderr are asynchronous, and a framed compiler error is long.
+//
+// It does mean a leak reads as a clean failure from the outside, so it hides the
+// class of bug #426 was. `POVESTE_NO_FORCE_EXIT` below is how that stays visible
+// without removing it — CI sets it for one step, where a leak is a hang again.
+//
+// Asserting on the reported handle list instead was tried and does not work: a
+// clean failed build leaves transient ones (`Immediate`, `FSReqCallback`), and the
+// allowance needed to go green has to include `FSReqCallback` — most of what the
+// sveltekit leak shows as. Whether the loop drains is the question (#433).
+/**
+ * A build asked to prove it drains: the forced exit below is skipped and what is
+ * still holding the loop open is printed.
+ *
+ * The exit code cannot carry that on its own. Forcing the exit makes a process
+ * that leaks look exactly like one that does not, which is what left the CI
+ * guard's hang branch unreachable and the #426 class of defect undetectable
+ * (#433). Under this flag a leak is a hang again, which is measurable, and the
+ * handle list says what to go and close.
+ *
+ * For CI, not for users — a leak should not be the difference between a build
+ * that ends and one that does not.
+ */
+function proveItDrains() {
+    return !!process.env.POVESTE_NO_FORCE_EXIT;
+}
 function run(command) {
     return command().then(() => undefined, (error) => {
         console.error(error);
         process.exitCode = 1;
+        if (proveItDrains()) {
+            setImmediate(() => {
+                console.error(`POVESTE_ACTIVE_HANDLES: ${JSON.stringify(process.getActiveResourcesInfo())}`);
+            });
+            return;
+        }
         setTimeout(() => process.exit(1), 500).unref();
     });
 }

package/dist/node/build.js

@@ -54,6 +54,13 @@ export async function build(ctx) {
         optimizeDeps: { include: [], noDiscovery: true },
     }));
     await server.pluginContainer.buildStart({});
+    // Cleanup a plugin registers runs however this ends. `onBuildEnd` cannot be that
+    // channel: "the build ended" and "the build ended well" are different events, and
+    // plugins publish results from the latter (#434).
+    const cleanupCallbacks = [];
+    const onCleanup = (cb) => {
+        cleanupCallbacks.push(cb);
+    };
     // Everything from here is wrapped so the server is closed on the way out
     // whichever way that is — it is the other handle that kept a failed build
     // alive (#405). `serverClosed` keeps the existing order rather than moving the
@@ -70,7 +77,7 @@ export async function build(ctx) {
         for (const plugin of ctx.config.plugins) {
             if (plugin.onBuild) {
                 const api = new BuildPluginApi(ctx, plugin, moduleLoader);
-                await plugin.onBuild(api);
+                await plugin.onBuild(api, onCleanup);
                 changeViteConfigCallbacks.push(...api.changeViteConfigCallbacks);
                 buildEndCallbacks.push(...api.buildEndCallbacks);
                 previewStoryCallbacks.push(...api.previewStoryCallbacks);
@@ -285,6 +292,9 @@ export async function build(ctx) {
         if (!serverClosed) {
             await wrapLogError('server.close', () => server.close());
         }
+        for (const cb of cleanupCallbacks) {
+            await wrapLogError('plugin.onBuild.onCleanup', () => cb());
+        }
     }
 }
 function generateBaseHtml(head, body, ctx) {

package/dist/node/cleanup.d.ts

@@ -0,0 +1,8 @@
+import type { Awaitable } from '@poveste/shared';
+export declare function onPovesteCleanup(cb: () => Awaitable<void>): void;
+/**
+ * Runs every registered callback and forgets them, so a `poveste dev` restart does
+ * not close the same thing twice. Logged rather than thrown: a teardown that fails
+ * must not replace whatever failure brought us here.
+ */
+export declare function runPovesteCleanups(): Promise<void>;

package/dist/node/cleanup.js

@@ -0,0 +1,28 @@
+import { wrapLogError } from './util/log.js';
+/**
+ * Teardown for things a plugin opens while the config is being resolved, before
+ * any command hook has run.
+ *
+ * `onBuild`'s own `onCleanup` covers what a plugin opens during a build. It cannot
+ * cover what already existed: `@poveste/plugin-nuxt` loads Nuxt in `defaultConfig`,
+ * so between that and the `onBuild` loop there is a window — finding the stories,
+ * resolving the Vite config, starting the collection server — where a failure left
+ * Nuxt running with nothing registered to close it (#434).
+ *
+ * Registered here, its lifetime starts where the resource does.
+ */
+const callbacks = [];
+export function onPovesteCleanup(cb) {
+    callbacks.push(cb);
+}
+/**
+ * Runs every registered callback and forgets them, so a `poveste dev` restart does
+ * not close the same thing twice. Logged rather than thrown: a teardown that fails
+ * must not replace whatever failure brought us here.
+ */
+export async function runPovesteCleanups() {
+    const pending = callbacks.splice(0, callbacks.length);
+    for (const cb of pending) {
+        await wrapLogError('poveste.cleanup', () => cb());
+    }
+}

package/dist/node/collect/index.js

@@ -79,18 +79,23 @@ export function useCollectStories(options, ctx) {
         });
     }
     async function executeStoryFile(storyFile) {
+        // The channel belongs to this execution, and nothing used to close it. On a
+        // build that fails, the executions still in flight are abandoned mid-run and
+        // their main-thread ports stay open and listening — enough live handles to
+        // keep the process alive with nothing left to do (#426).
+        let channel;
         try {
-            const { workerPort } = createChannel();
+            channel = createChannel();
             const payload = {
                 root: server.config.root,
                 base: server.config.base,
                 storyFile,
-                port: workerPort,
+                port: channel.workerPort,
                 defineGlobals,
             };
             const { storyData } = await threadPool.run(payload, {
                 transferList: [
-                    workerPort,
+                    channel.workerPort,
                 ],
             });
             if (storyData.length === 0) {
@@ -125,6 +130,9 @@ export function useCollectStories(options, ctx) {
                 throw e;
             }
         }
+        finally {
+            channel?.port.close();
+        }
     }
     async function destroy() {
         await threadPool.destroy();

package/dist/node/commands/build.js

@@ -1,9 +1,17 @@
 import { build } from '../build.js';
+import { runPovesteCleanups } from '../cleanup.js';
 import { createContext } from '../context.js';
 export async function buildCommand(options) {
-    const ctx = await createContext({
-        configFile: options.config,
-        mode: 'build',
-    });
-    await build(ctx);
+    // Plugins open things while the config is resolved — before any hook here has
+    // run — so the teardown has to span the command, not one phase of it (#434).
+    try {
+        const ctx = await createContext({
+            configFile: options.config,
+            mode: 'build',
+        });
+        await build(ctx);
+    }
+    finally {
+        await runPovesteCleanups();
+    }
 }

package/dist/node/commands/dev.js

@@ -1,54 +1,62 @@
 import chokidar from 'chokidar';
 import pc from 'picocolors';
+import { runPovesteCleanups } from '../cleanup.js';
 import { resolveConfigFile } from '../config.js';
 import { createContext } from '../context.js';
 import { createServer } from '../server.js';
 import { resolvePort } from './port.js';
 export async function devCommand(options) {
-    const port = resolvePort(options.port, 'dev');
-    let stop;
-    async function start() {
-        const ctx = await createContext({
-            configFile: options.config,
-            mode: 'dev',
-        });
-        const { server, viteConfigFile, close } = await createServer(ctx, {
-            port,
-            open: options.open,
-            host: options.host,
-        });
-        server.printUrls();
-        // Poveste config watcher
-        let watcher;
-        if (viteConfigFile) {
-            watcher = chokidar.watch(viteConfigFile, {
+    // Plugins open things while the config is resolved — before any hook here has
+    // run — so the teardown has to span the command, not one phase of it (#434).
+    try {
+        const port = resolvePort(options.port, 'dev');
+        let stop;
+        async function start() {
+            const ctx = await createContext({
+                configFile: options.config,
+                mode: 'dev',
+            });
+            const { server, viteConfigFile, close } = await createServer(ctx, {
+                port,
+                open: options.open,
+                host: options.host,
+            });
+            server.printUrls();
+            // Poveste config watcher
+            let watcher;
+            if (viteConfigFile) {
+                watcher = chokidar.watch(viteConfigFile, {
+                    ignoreInitial: true,
+                });
+                watcher.on('change', () => {
+                    restart('Vite');
+                });
+            }
+            return async () => {
+                await watcher?.close();
+                await close();
+            };
+        }
+        async function restart(source) {
+            if (stop) {
+                console.log(pc.blue(`${source} config changed, restarting...`));
+                await stop();
+                stop = null; // Don't call stop again until new start() is done
+                stop = await start();
+            }
+        }
+        stop = await start();
+        const configFile = await resolveConfigFile(undefined, options.config);
+        if (configFile) {
+            const watcher = chokidar.watch(configFile, {
                 ignoreInitial: true,
             });
             watcher.on('change', () => {
-                restart('Vite');
+                restart('Poveste');
             });
         }
-        return async () => {
-            await watcher?.close();
-            await close();
-        };
-    }
-    async function restart(source) {
-        if (stop) {
-            console.log(pc.blue(`${source} config changed, restarting...`));
-            await stop();
-            stop = null; // Don't call stop again until new start() is done
-            stop = await start();
-        }
     }
-    stop = await start();
-    const configFile = await resolveConfigFile(undefined, options.config);
-    if (configFile) {
-        const watcher = chokidar.watch(configFile, {
-            ignoreInitial: true,
-        });
-        watcher.on('change', () => {
-            restart('Poveste');
-        });
+    finally {
+        await runPovesteCleanups();
     }
 }

package/dist/node/commands/preview.js

@@ -1,20 +1,28 @@
+import { runPovesteCleanups } from '../cleanup.js';
 import { createContext } from '../context.js';
 import { startPreview } from '../preview.js';
 import { resolvePort } from './port.js';
 export async function previewCommand(options) {
-    const port = resolvePort(options.port, 'preview');
-    const ctx = await createContext({
-        mode: 'build',
-    });
-    for (const plugin of ctx.config.plugins) {
-        if (plugin.onPreview) {
-            await plugin.onPreview();
+    // Plugins open things while the config is resolved — before any hook here has
+    // run — so the teardown has to span the command, not one phase of it (#434).
+    try {
+        const port = resolvePort(options.port, 'preview');
+        const ctx = await createContext({
+            mode: 'build',
+        });
+        for (const plugin of ctx.config.plugins) {
+            if (plugin.onPreview) {
+                await plugin.onPreview();
+            }
         }
+        const { printUrls } = await startPreview({
+            port,
+            host: options.host,
+            open: options.open,
+        }, ctx);
+        printUrls();
+    }
+    finally {
+        await runPovesteCleanups();
     }
-    const { printUrls } = await startPreview({
-        port,
-        host: options.host,
-        open: options.open,
-    }, ctx);
-    printUrls();
 }

package/dist/node/index.d.ts

@@ -1,3 +1,4 @@
+export { onPovesteCleanup } from './cleanup.js';
 export { defaultColors } from './colors.js';
 export * from './config.js';
 export * from './plugin.js';

package/dist/node/index.js

@@ -1,7 +1,8 @@
+// A plugin that generates story source needs to reference poveste's own
+// vendored copies of Vue and the controls from inside that generated code.
+export { onPovesteCleanup } from './cleanup.js';
 export { defaultColors } from './colors.js';
 export * from './config.js';
 export * from './plugin.js';
-// A plugin that generates story source needs to reference poveste's own
-// vendored copies of Vue and the controls from inside that generated code.
 export { getInjectedImport } from './util/vendors.js';
 export * from '@poveste/shared';

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "poveste",
   "type": "module",
-  "version": "0.8.2",
+  "version": "0.10.0",
   "description": "Interactive component playgrounds for Vue, Svelte and Nuxt — a maintained, drop-in successor to histoire",
   "author": {
     "name": "Sorin Gitlan"
@@ -98,10 +98,10 @@
     "sirv": "^3.0.0",
     "unhead": "^3.1.0",
     "vite-node": "^6.0.0",
-    "@poveste/app": "^0.8.2",
-    "@poveste/controls": "^0.8.2",
-    "@poveste/shared": "^0.8.2",
-    "@poveste/vendors": "^0.8.2"
+    "@poveste/app": "^0.10.0",
+    "@poveste/controls": "^0.10.0",
+    "@poveste/shared": "^0.10.0",
+    "@poveste/vendors": "^0.10.0"
   },
   "devDependencies": {
     "@types/fs-extra": "^11.0.4",