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

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";

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));
@@ -68,6 +69,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.37",
   "description": "Local preview shell for Notion custom block workers.",
   "license": "MIT",
   "repository": {
@@ -38,8 +38,8 @@
     "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",