@notionhq/custom-blocks-dev-shell 0.1.36 → 0.1.38

package/dist-cli/build-block-registry.js

@@ -0,0 +1,9 @@
+import { BLOCK_BASE_PORT } from "./ports.js";
+/** The registry for a worker's blocks, assuming sequential port assignment. */
+export function buildBlockRegistry(blocks, basePort = BLOCK_BASE_PORT) {
+    return blocks.map((capability, index) => ({
+        key: capability.key,
+        name: capability.key,
+        url: `http://localhost:${basePort + index}/`,
+    }));
+}

package/dist-cli/convert.js

@@ -9,7 +9,8 @@ import { readFileSync } from "node:fs";
 import * as v from "valibot";
 import { convertPublicApiPropertyValue, isDataSourceValue, matchesPropertyType, } from "./convert-values.js";
 import { NOTION_PROPERTY_TYPES, sourceFileSchema } from "./data-sources.js";
-import { claimUniqueKey, parseLongOptions, slugify } from "./utils.js";
+import { formatUnknownError } from "./errors.js";
+import { claimUniqueKey, parseCliArgs, slugify } from "./utils.js";
 const SUPPORTED_TYPES = new Set(NOTION_PROPERTY_TYPES);
 /** The spelling of "text" in the local file format. */
 const UNSUPPORTED_TYPE_FALLBACK = "rich_text";
@@ -19,18 +20,25 @@ export function parseConvertArgs(argv) {
         key: undefined,
         name: undefined,
     };
-    parseLongOptions(argv, {
-        "--in": value => {
-            args.input = value;
-        },
-        "--key": value => {
-            args.key = value;
-        },
-        "--name": value => {
-            args.name = value;
-        },
-    }, arg => {
+    const rejectUnknown = (arg) => {
         throw new Error(`Unknown convert option "${arg}". Supported: --in <file>, --key <key>, --name <name>.`);
+    };
+    parseCliArgs({
+        argv,
+        handlers: {
+            "--in": value => {
+                args.input = value;
+            },
+            "--key": value => {
+                args.key = value;
+            },
+            "--name": value => {
+                args.name = value;
+            },
+        },
+        onUnknown: rejectUnknown,
+        // This command accepts no positional arguments.
+        onPositional: rejectUnknown,
     });
     return args;
 }
@@ -182,7 +190,7 @@ export async function runConvert(argv) {
             raw = readFileSync(args.input, "utf-8");
         }
         catch (error) {
-            throw new Error(`Could not read ${args.input}: ${error.message}`);
+            throw new Error(`Could not read ${args.input}: ${formatUnknownError(error)}`);
         }
     }
     else {
@@ -196,7 +204,7 @@ export async function runConvert(argv) {
         parsed = JSON.parse(raw);
     }
     catch (error) {
-        throw new Error(`Input is not valid JSON — ${error.message}`);
+        throw new Error(`Input is not valid JSON — ${formatUnknownError(error)}`);
     }
     const { source, warnings } = convertSample(parsed, {
         ...(args.key !== undefined ? { key: args.key } : {}),

package/dist-cli/data-sources.js

@@ -7,6 +7,7 @@
 import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { basename, resolve } from "node:path";
 import * as v from "valibot";
+import { formatUnknownError } from "./errors.js";
 const DEV_SHELL_DATA_SOURCE_TYPES = [
     "built-in",
     "worker",
@@ -79,7 +80,7 @@ function readSource(file) {
         parsed = JSON.parse(readFileSync(file, "utf-8"));
     }
     catch (error) {
-        throw new Error(`${file}: not valid JSON — ${error.message}`);
+        throw new Error(`${file}: not valid JSON — ${formatUnknownError(error)}`);
     }
     if (Array.isArray(parsed)) {
         throw new Error(`${file}: must be a JSON object`);

package/dist-cli/dev-shell-launcher.js

@@ -8,12 +8,14 @@
 import { existsSync, readFileSync } from "node:fs";
 import { createRequire } from "node:module";
 import { basename, dirname, join, resolve } from "node:path";
-import { buildBlockRegistry, writeBlockViteConfig, } from "./block-server.js";
+import { buildBlockRegistry, } from "./build-block-registry.js";
 import { readDataSources } from "./data-sources.js";
+import { formatUnknownErrorWithStack } from "./errors.js";
 import { materializeWorkerSchemaDataSources } from "./materialize.js";
 import { BLOCK_BASE_PORT, parsePort, SHELL_PORT, validateBlockPortRange, validateShellPort, } from "./ports.js";
 import { installProcessSignalHandlers, ProcessSupervisor, } from "./process-supervisor.js";
-import { parseLongOptions } from "./utils.js";
+import { parseCliArgs } from "./utils.js";
+import { writeBlockViteConfig } from "./vite-block-server.js";
 import { blockCapabilities, findWorkerDir, generateWorkerManifest, } from "./worker-manifest.js";
 const dim = "\x1b[2m";
 const bold = "\x1b[1m";
@@ -58,18 +60,43 @@ export function parseWorkerLaunchArgs(argv) {
         shellPort: SHELL_PORT,
         blockBasePort: BLOCK_BASE_PORT,
     };
-    parseLongOptions(argv, {
-        "--worker": value => {
-            if (value.length === 0) {
-                throw new Error("--worker requires a path to a worker directory.");
-            }
-            args.worker = value;
+    let hasPositionalWorker = false;
+    parseCliArgs({
+        argv,
+        handlers: {
+            "--worker": value => {
+                if (value.length === 0) {
+                    throw new Error("--worker requires a path to a worker directory.");
+                }
+                // Reject --worker after a positional worker path.
+                if (hasPositionalWorker) {
+                    throw new Error("Cannot combine --worker with a positional worker path.");
+                }
+                args.worker = value;
+            },
+            "--port": value => {
+                args.shellPort = parsePort("--port", value);
+            },
+            "--block-base-port": value => {
+                args.blockBasePort = parsePort("--block-base-port", value);
+            },
         },
-        "--port": value => {
-            args.shellPort = parsePort("--port", value);
+        onUnknown: arg => {
+            throw new Error(`Unknown dev shell option "${arg}". Supported: --worker <dir>, ` +
+                `--port <port>, --block-base-port <port>.`);
         },
-        "--block-base-port": value => {
-            args.blockBasePort = parsePort("--block-base-port", value);
+        onPositional: arg => {
+            // The published launcher passes its optional worker path positionally.
+            // Reject a second positional path.
+            if (hasPositionalWorker) {
+                throw new Error("Only one positional worker path may be provided.");
+            }
+            // Reject a positional path after --worker.
+            if (args.worker !== undefined) {
+                throw new Error("Cannot combine --worker with a positional worker path.");
+            }
+            hasPositionalWorker = true;
+            args.worker = arg;
         },
     });
     return args;
@@ -188,7 +215,7 @@ export async function launchDevShell(options) {
         printSummary(args, plan.registry);
     }
     catch (error) {
-        console.error(`Failed to start dev shell: ${error instanceof Error ? error.message : error}`);
+        console.error(`Failed to start dev shell:\n${formatUnknownErrorWithStack(error)}`);
         process.exitCode = 1;
         run.shutdown("SIGTERM");
     }

package/dist-cli/errors.js

@@ -0,0 +1,8 @@
+/** Format an unknown error as a message without a stack trace. */
+export function formatUnknownError(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/** Format an unknown error with its stack when one is available. */
+export function formatUnknownErrorWithStack(error) {
+    return error instanceof Error ? (error.stack ?? error.message) : String(error);
+}

package/dist-cli/process-supervisor.js

@@ -3,7 +3,7 @@
  */
 import { spawn } from "node:child_process";
 import { createInterface } from "node:readline";
-import { makeChangeLogger } from "./block-server.js";
+import { makeChangeLogger } from "./vite-block-server.js";
 const SHUTDOWN_GRACE_MS = 1500;
 const dim = "\x1b[2m";
 const reset = "\x1b[0m";
@@ -17,7 +17,7 @@ export class ProcessSupervisor {
     }
     addResource(resource) {
         if (this.shuttingDown) {
-            closeResource(resource);
+            void closeResource(resource);
             return;
         }
         this.resources.push(resource);
@@ -49,7 +49,11 @@ export class ProcessSupervisor {
                 this.shutdown("SIGTERM");
             });
             proc.on("exit", code => {
-                this.processes.delete(proc);
+                // Retain an unexpectedly failed process until cleanup. Its PID may
+                // still identify a detached process group with live descendants.
+                if (!this.shuttingDown && (code === 0 || code === null)) {
+                    this.processes.delete(proc);
+                }
                 if (this.shuttingDown || code === 0 || code === null) {
                     return;
                 }
@@ -61,6 +65,9 @@ export class ProcessSupervisor {
     }
     shutdown(signal) {
         if (this.shuttingDown) {
+            if (signal !== "exit") {
+                this.forceShutdown();
+            }
             return;
         }
         this.shuttingDown = true;
@@ -68,44 +75,82 @@ export class ProcessSupervisor {
             (this.processes.size > 0 || this.resources.length > 0)) {
             console.log(`\n${dim}Shutting down...${reset}`);
         }
-        for (const resource of this.resources) {
-            closeResource(resource);
-        }
         for (const [proc, detached] of this.processes) {
             killProcess(proc, detached, "SIGTERM");
         }
         if (signal === "exit") {
+            for (const resource of this.resources) {
+                void closeResource(resource);
+            }
             return;
         }
-        const timer = setTimeout(() => {
-            for (const [proc, detached] of this.processes) {
-                killProcess(proc, detached, "SIGKILL");
-            }
-            process.exit(process.exitCode ?? 0);
-        }, SHUTDOWN_GRACE_MS);
-        timer.unref();
+        void this.finishShutdown();
+    }
+    async finishShutdown() {
+        const resourceCleanup = Promise.all(this.resources.map(resource => closeResource(resource)));
+        const processCleanup = Promise.all([...this.processes.keys()].map(proc => waitForExit(proc)));
+        let finished = false;
+        await Promise.race([
+            Promise.all([resourceCleanup, processCleanup]).then(() => {
+                finished = true;
+            }),
+            delay(SHUTDOWN_GRACE_MS),
+        ]);
+        if (!finished) {
+            this.forceShutdown();
+            return;
+        }
+        // A process can exit before its descendants do. Re-signal every
+        // remaining process group even after the direct child has exited.
+        this.forceKillProcesses();
+        process.exit(process.exitCode ?? 0);
+    }
+    forceShutdown() {
+        this.forceKillProcesses();
+        process.exit(process.exitCode ?? 130);
+    }
+    forceKillProcesses() {
+        for (const [proc, detached] of this.processes) {
+            killProcess(proc, detached, "SIGKILL", true);
+        }
     }
 }
-function closeResource(resource) {
+async function closeResource(resource) {
     try {
-        resource();
+        await resource();
     }
     catch { }
 }
-function killProcess(proc, detached, signal) {
-    if (proc.pid === undefined || proc.killed) {
+function killProcess(proc, detached, signal, force = false) {
+    const pid = proc.pid;
+    if (pid === undefined) {
         return;
     }
     try {
         if (detached && process.platform !== "win32") {
-            process.kill(-proc.pid, signal);
+            process.kill(-pid, signal);
+            return;
         }
-        else {
+        if (force || isProcessRunning(proc)) {
             proc.kill(signal);
         }
     }
     catch { }
 }
+function isProcessRunning(proc) {
+    return proc.exitCode === null && proc.signalCode === null;
+}
+function waitForExit(proc) {
+    if (proc.exitCode !== null || proc.signalCode !== null) {
+        return Promise.resolve();
+    }
+    return new Promise(resolve => {
+        proc.once("exit", () => resolve());
+    });
+}
+function delay(milliseconds) {
+    return new Promise(resolve => setTimeout(resolve, milliseconds));
+}
 export function installProcessSignalHandlers(run) {
     for (const signal of ["SIGINT", "SIGTERM", "SIGHUP"]) {
         process.on(signal, () => run.shutdown(signal));

package/dist-cli/published-cli.js

@@ -15,6 +15,7 @@ import { fileURLToPath } from "node:url";
 import { runConvert } from "./convert.js";
 import { readDataSources } from "./data-sources.js";
 import { launchDevShell } from "./dev-shell-launcher.js";
+import { formatUnknownErrorWithStack } from "./errors.js";
 import { copyPrebuiltDataSources } from "./prebuilt.js";
 import { serveUi } from "./serve-ui.js";
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -50,7 +51,11 @@ const createShellLaunch = async ({ args, plan, log }) => {
     }
     return {
         processes: [],
-        resources: [() => server.close()],
+        resources: [
+            () => new Promise(resolve => {
+                server.close(() => resolve());
+            }),
+        ],
     };
 };
 async function main() {
@@ -68,6 +73,6 @@ async function main() {
     });
 }
 main().catch(error => {
-    console.error(error instanceof Error ? error.message : error);
+    console.error(formatUnknownErrorWithStack(error));
     process.exitCode = 1;
 });

package/dist-cli/serve-ui.js

@@ -10,6 +10,7 @@
 import { readFileSync } from "node:fs";
 import { createServer } from "node:http";
 import { extname, join, normalize, resolve, sep } from "node:path";
+import { formatUnknownError } from "./errors.js";
 const CONTENT_TYPES = {
     ".html": "text/html; charset=utf-8",
     ".js": "text/javascript; charset=utf-8",
@@ -73,7 +74,7 @@ export function serveUi(distDir, port, config, addPrebuiltData) {
             }
             catch (error) {
                 res.writeHead(500, { "Content-Type": CONTENT_TYPES[".json"] });
-                res.end(JSON.stringify({ error: error.message }));
+                res.end(JSON.stringify({ error: formatUnknownError(error) }));
                 return;
             }
             res.writeHead(200, { "Content-Type": CONTENT_TYPES[".json"] });

package/dist-cli/utils.js

@@ -24,11 +24,7 @@ export function claimUniqueKey(base, used) {
     used.add(key);
     return key;
 }
-/**
- * Parse long options in both `--name value` and `--name=value` forms.
- * Unknown options are passed to `onUnknown`. Callers can ignore or reject them.
- */
-export function parseLongOptions(argv, handlers, onUnknown = () => { }) {
+export function parseCliArgs({ argv, handlers, onUnknown, onPositional, }) {
     const takeValue = (name, index) => {
         const value = argv[index];
         if (value === undefined || value.startsWith("--")) {
@@ -42,7 +38,12 @@ export function parseLongOptions(argv, handlers, onUnknown = () => { }) {
         const name = separator === -1 ? arg : arg.slice(0, separator);
         const handler = handlers[name];
         if (handler === undefined) {
-            onUnknown(arg);
+            if (arg.startsWith("-")) {
+                onUnknown(arg);
+            }
+            else {
+                onPositional(arg);
+            }
             continue;
         }
         const value = separator === -1 ? takeValue(name, ++index) : arg.slice(separator + 1);

package/dist-cli/{block-server.js → vite-block-server.js}

@@ -1,18 +1,9 @@
 /**
- * Provides shared Vite server setup for both dev shell launchers. It builds the block registry,
- * generates a Vite config for each block, and formats Vite change logs.
+ * Provides shared Vite server setup for both dev shell launchers. It generates a
+ * Vite config for each block and formats Vite change logs.
  */
 import { existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { relative, resolve } from "node:path";
-import { BLOCK_BASE_PORT } from "./ports.js";
-/** The registry for a worker's blocks, assuming sequential port assignment. */
-export function buildBlockRegistry(blocks, basePort = BLOCK_BASE_PORT) {
-    return blocks.map((capability, index) => ({
-        key: capability.key,
-        name: capability.key,
-        url: `http://localhost:${basePort + index}/`,
-    }));
-}
 const ANSI_PATTERN = /\x1b\[[0-9;]*m/g;
 const VITE_CHANGE_PATTERN = /\b(page reload|hmr update)\s+(.+)$/;
 /**
@@ -116,6 +107,11 @@ export default {
 	...resolved,
 	root: here("${toRoot}"),
 	cacheDir: here("${toCache}"),
+	server: {
+		...(resolved.server ?? {}),
+		// Block servers are local development dependencies of the shell.
+		host: "127.0.0.1",
+	},
 	define: {
 		...(resolved.define ?? {}),
 		// Initialization handshake scenarios fixture uses this key to identify the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@notionhq/custom-blocks-dev-shell",
-  "version": "0.1.36",
+  "version": "0.1.38",
   "description": "Local preview shell for Notion custom block workers.",
   "license": "MIT",
   "repository": {
@@ -34,12 +34,13 @@
     "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
     "@vitejs/plugin-react": "^6.0.1",
+    "@vitest/coverage-v8": "^4.1.5",
     "tailwindcss": "^4.2.4",
     "typescript": "^6.0.3",
     "vite": "^8.0.10",
     "vitest": "^4.1.5",
-    "@notionhq/custom-blocks-host": "0.0.0",
-    "@notionhq/custom-blocks-protocol": "0.1.0"
+    "@notionhq/custom-blocks-protocol": "0.1.0",
+    "@notionhq/custom-blocks-host": "0.0.0"
   },
   "scripts": {
     "dev": "vite",