npm - @notionhq/custom-blocks-dev-shell - Versions diffs - 0.1.33 → 0.1.35 - Mend

@notionhq/custom-blocks-dev-shell 0.1.33 → 0.1.35

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (12) hide show

package/bin/cli.js +6 -1
package/dist/assets/{index-kNlMQeXD.js → index-kz317NXT.js} +1 -1
package/dist/index.html +1 -1
package/dist-cli/block-server.js +3 -6
package/dist-cli/convert.js +14 -32
package/dist-cli/dev-shell-launcher.js +195 -0
package/dist-cli/ports.js +36 -0
package/dist-cli/process-supervisor.js +119 -0
package/dist-cli/published-cli.js +73 -0
package/dist-cli/utils.js +25 -0
package/package.json +3 -3
package/dist-cli/main.js +0 -271

package/dist/index.html CHANGED Viewed

@@ -4,7 +4,7 @@
 		<meta charset="UTF-8" />
 		<meta name="viewport" content="width=device-width, initial-scale=1.0" />
 		<title>Workers local shell</title>
-		<script type="module" crossorigin src="/assets/index-kNlMQeXD.js"></script>
+		<script type="module" crossorigin src="/assets/index-kz317NXT.js"></script>
 		<link rel="stylesheet" crossorigin href="/assets/index-DpKdfNws.css">
 	</head>
 	<body>

package/dist-cli/block-server.js CHANGED Viewed

@@ -1,13 +1,10 @@
 /**
- * Per-block Vite server plumbing shared by the repo dev script
- * (`scripts/dev.ts`) and the published dev shell CLI (`cli/main.ts`).
+ * 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.
  */
 import { existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { relative, resolve } from "node:path";
-/** First port handed to per-block Vite servers; blocks count up from here. */
-export const BLOCK_BASE_PORT = 9876;
-/** Port the dev shell UI is served on. */
-export const SHELL_PORT = 9873;
+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) => ({

package/dist-cli/convert.js CHANGED Viewed

@@ -9,7 +9,7 @@ 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, slugify } from "./utils.js";
+import { claimUniqueKey, parseLongOptions, 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,37 +19,19 @@ export function parseConvertArgs(argv) {
         key: undefined,
         name: undefined,
     };
-    const takeValue = (name, index) => {
-        const value = argv[index];
-        if (value === undefined || value.startsWith("--")) {
-            throw new Error(`${name} requires a value.`);
-        }
-        return value;
-    };
-    for (let index = 0; index < argv.length; index++) {
-        const arg = argv[index];
-        if (arg === "--in") {
-            args.input = takeValue("--in", ++index);
-        }
-        else if (arg.startsWith("--in=")) {
-            args.input = arg.slice("--in=".length);
-        }
-        else if (arg === "--key") {
-            args.key = takeValue("--key", ++index);
-        }
-        else if (arg.startsWith("--key=")) {
-            args.key = arg.slice("--key=".length);
-        }
-        else if (arg === "--name") {
-            args.name = takeValue("--name", ++index);
-        }
-        else if (arg.startsWith("--name=")) {
-            args.name = arg.slice("--name=".length);
-        }
-        else {
-            throw new Error(`Unknown convert option "${arg}". Supported: --in <file>, --key <key>, --name <name>.`);
-        }
-    }
+    parseLongOptions(argv, {
+        "--in": value => {
+            args.input = value;
+        },
+        "--key": value => {
+            args.key = value;
+        },
+        "--name": value => {
+            args.name = value;
+        },
+    }, arg => {
+        throw new Error(`Unknown convert option "${arg}". Supported: --in <file>, --key <key>, --name <name>.`);
+    });
     return args;
 }
 const sampleInputSchema = v.pipe(v.looseObject({

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

@@ -0,0 +1,195 @@
+/**
+ * Shared orchestration for the repository and published dev shell launchers.
+ *
+ * It builds the worker and reads its manifest, starts one Vite server per
+ * custom block, and owns process and resource cleanup. Each launcher entry point
+ * supplies a small shell adapter, but otherwise delegates to this module.
+ */
+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 { readDataSources } from "./data-sources.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 { blockCapabilities, findWorkerDir, generateWorkerManifest, } from "./worker-manifest.js";
+const dim = "\x1b[2m";
+const bold = "\x1b[1m";
+const cyan = "\x1b[36m";
+const reset = "\x1b[0m";
+const label = (name) => `${cyan}[${name}]${reset}`;
+export async function prepareWorkerLaunchPlan(workerDir, options = {}) {
+    const root = resolve(workerDir);
+    if (!existsSync(resolve(root, "node_modules"))) {
+        throw new Error(`No node_modules in ${root}. Install the worker's dependencies first ` +
+            `(e.g. \`npm install\`), then rerun.`);
+    }
+    const { manifest, manifestPath } = await generateWorkerManifest(root, {
+        build: options.build,
+    });
+    const capabilities = blockCapabilities(manifest);
+    const blockBasePort = options.blockBasePort ?? BLOCK_BASE_PORT;
+    validateBlockPortRange(blockBasePort, capabilities.length);
+    const blocks = capabilities.map((capability, index) => {
+        const blockDir = resolve(root, capability.config.source.path);
+        return {
+            capability,
+            blockDir,
+            configFile: writeBlockViteConfig(root, blockDir, capability),
+            port: blockBasePort + index,
+        };
+    });
+    const dataDir = resolve(root, "src/data");
+    materializeWorkerSchemaDataSources(manifest, dataDir);
+    return {
+        workerDir: root,
+        dataDir,
+        manifestPath,
+        blocks,
+        registry: buildBlockRegistry(capabilities, blockBasePort),
+        dataSources: readDataSources(dataDir),
+    };
+}
+export function parseWorkerLaunchArgs(argv) {
+    const args = {
+        worker: undefined,
+        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;
+        },
+        "--port": value => {
+            args.shellPort = parsePort("--port", value);
+        },
+        "--block-base-port": value => {
+            args.blockBasePort = parsePort("--block-base-port", value);
+        },
+    });
+    return args;
+}
+function resolveWorkerViteBin(workerDir) {
+    let vitePkgPath;
+    try {
+        const workerRequire = createRequire(join(workerDir, "package.json"));
+        vitePkgPath = workerRequire.resolve("vite/package.json");
+    }
+    catch {
+        throw new Error(`Could not resolve "vite" from ${workerDir}. Add vite to the worker's ` +
+            `devDependencies and reinstall.`);
+    }
+    const vitePkg = JSON.parse(readFileSync(vitePkgPath, "utf-8"));
+    const bin = typeof vitePkg.bin === "string" ? vitePkg.bin : vitePkg.bin?.vite;
+    if (bin === undefined) {
+        throw new Error(`The vite package at ${vitePkgPath} exposes no bin.`);
+    }
+    return resolve(dirname(vitePkgPath), bin);
+}
+function createBlockProcesses(plan) {
+    if (plan.blocks.length === 0) {
+        return [];
+    }
+    const viteBin = resolveWorkerViteBin(plan.workerDir);
+    return plan.blocks.map(block => ({
+        name: block.capability.key,
+        command: process.execPath,
+        args: [
+            viteBin,
+            "--config",
+            block.configFile,
+            "--port",
+            String(block.port),
+            "--strictPort",
+        ],
+        cwd: plan.workerDir,
+        detached: process.platform !== "win32",
+    }));
+}
+function logNamed(name, message) {
+    console.log(`${label(name)} ${message}`);
+}
+function printSummary(args, registry) {
+    console.log("");
+    console.log(`${bold}Dev shell${reset}`);
+    console.log(`  ${label("dev-shell")} ${dim}http://localhost:${args.shellPort}${reset}`);
+    if (registry.length > 0) {
+        console.log("");
+        console.log(`${bold}Blocks${reset}`);
+        for (const entry of registry) {
+            console.log(`  ${label(entry.key)} ${dim}${entry.url}${reset}`);
+        }
+    }
+    console.log("");
+}
+function resolveWorkerLaunch(options) {
+    const args = parseWorkerLaunchArgs(options.argv);
+    const workerDir = args.worker === undefined
+        ? findWorkerDir(options.detectFromDir)
+        : resolve(options.workerBaseDir, args.worker);
+    if (workerDir === undefined) {
+        throw new Error("No worker found: run from inside a worker directory, or pass --worker <dir>.");
+    }
+    if (args.worker === undefined) {
+        console.log(`Detected a worker at ${workerDir}.`);
+    }
+    return { args, workerDir };
+}
+function logWorkerPlan(workerName, plan) {
+    logNamed(workerName, `Wrote ${plan.manifestPath}`);
+    if (plan.blocks.length === 0) {
+        logNamed(workerName, "Worker declares no custom blocks.");
+    }
+    logNamed(workerName, plan.dataSources.length > 0
+        ? `Data sources from src/data: ${plan.dataSources
+            .map(source => source.name)
+            .join(", ")}`
+        : "No data sources — create src/data/<key>.json files " +
+            "(format: node_modules/@notionhq/custom-blocks-dev-shell/docs/data-sources.md).");
+}
+async function prepareWorkerLaunch(options) {
+    const { args, workerDir } = resolveWorkerLaunch(options);
+    const workerName = basename(workerDir);
+    logNamed(workerName, "Extracting worker manifest...");
+    const plan = await prepareWorkerLaunchPlan(workerDir, {
+        blockBasePort: args.blockBasePort,
+    });
+    logWorkerPlan(workerName, plan);
+    validateShellPort(args.shellPort, args.blockBasePort, plan.blocks.length);
+    const shell = await options.createShellLaunch({
+        args,
+        plan,
+        log: logNamed,
+    });
+    return { args, plan, shell };
+}
+export async function launchDevShell(options) {
+    const { installSignalHandlers = true } = options;
+    const callbacks = {
+        onChange: logNamed,
+        onUnexpectedExit: (name, code) => console.error(`${label(name)} dev server exited with code ${code}`),
+        onProcessError: (name, error) => console.error(`${label(name)} dev server failed: ${error.message}`),
+    };
+    const run = options.createRun?.() ?? new ProcessSupervisor(callbacks);
+    if (installSignalHandlers) {
+        installProcessSignalHandlers(run);
+    }
+    try {
+        const { args, plan, shell } = await prepareWorkerLaunch(options);
+        for (const resource of shell.resources) {
+            run.addResource(resource);
+        }
+        run.start([...shell.processes, ...createBlockProcesses(plan)]);
+        printSummary(args, plan.registry);
+    }
+    catch (error) {
+        console.error(`Failed to start dev shell: ${error instanceof Error ? error.message : error}`);
+        process.exitCode = 1;
+        run.shutdown("SIGTERM");
+    }
+}

package/dist-cli/ports.js ADDED Viewed

@@ -0,0 +1,36 @@
+/**
+ * Port defaults and validation shared by the repository and published launchers.
+ */
+/** First port handed to per-block Vite servers; blocks count up from here. */
+export const BLOCK_BASE_PORT = 9876;
+/** Port the dev shell UI is served on. */
+export const SHELL_PORT = 9873;
+/** Highest valid TCP port. */
+const MAX_PORT = 65535;
+/** Parse and validate a named CLI port option. */
+export function parsePort(name, raw) {
+    const port = Number(raw);
+    if (!Number.isInteger(port) || port <= 0 || port > MAX_PORT) {
+        throw new Error(`${name} requires a port number, got "${raw}".`);
+    }
+    return port;
+}
+/** Reject a sequential block-port range that would exceed the TCP port limit. */
+export function validateBlockPortRange(blockBasePort, blockCount) {
+    const lastPort = blockBasePort + blockCount - 1;
+    if (blockCount > 0 && lastPort > MAX_PORT) {
+        throw new Error(`--block-base-port ${blockBasePort} is too high for ${blockCount} ` +
+            `block servers; the last block port would be ${lastPort}, but ports ` +
+            `cannot exceed ${MAX_PORT}.`);
+    }
+}
+/** Reject a shell port that overlaps the sequential block-port range. */
+export function validateShellPort(shellPort, blockBasePort, blockCount) {
+    if (blockCount > 0 &&
+        shellPort >= blockBasePort &&
+        shellPort < blockBasePort + blockCount) {
+        throw new Error(`--port ${shellPort} collides with the block server ports ` +
+            `(${blockBasePort}–${blockBasePort + blockCount - 1}); ` +
+            `pick a port outside that range or move --block-base-port.`);
+    }
+}

package/dist-cli/process-supervisor.js ADDED Viewed

@@ -0,0 +1,119 @@
+/**
+ * Own child processes and non-child resources for one dev shell run.
+ */
+import { spawn } from "node:child_process";
+import { createInterface } from "node:readline";
+import { makeChangeLogger } from "./block-server.js";
+const SHUTDOWN_GRACE_MS = 1500;
+const dim = "\x1b[2m";
+const reset = "\x1b[0m";
+export class ProcessSupervisor {
+    callbacks;
+    processes = new Map();
+    resources = [];
+    shuttingDown = false;
+    constructor(callbacks) {
+        this.callbacks = callbacks;
+    }
+    addResource(resource) {
+        if (this.shuttingDown) {
+            closeResource(resource);
+            return;
+        }
+        this.resources.push(resource);
+    }
+    start(specs) {
+        for (const spec of specs) {
+            if (this.shuttingDown) {
+                return;
+            }
+            const detached = spec.detached ?? process.platform !== "win32";
+            const proc = spawn(spec.command, [...spec.args], {
+                cwd: spec.cwd,
+                stdio: ["ignore", "pipe", "inherit"],
+                detached,
+                env: spec.env === undefined
+                    ? process.env
+                    : { ...process.env, ...spec.env },
+            });
+            this.processes.set(proc, detached);
+            if (proc.stdout !== null) {
+                createInterface({ input: proc.stdout }).on("line", makeChangeLogger(message => this.callbacks.onChange(spec.name, message)));
+            }
+            proc.on("error", error => {
+                if (this.shuttingDown) {
+                    return;
+                }
+                this.callbacks.onProcessError(spec.name, error);
+                process.exitCode = 1;
+                this.shutdown("SIGTERM");
+            });
+            proc.on("exit", code => {
+                this.processes.delete(proc);
+                if (this.shuttingDown || code === 0 || code === null) {
+                    return;
+                }
+                this.callbacks.onUnexpectedExit(spec.name, code);
+                process.exitCode = code;
+                this.shutdown("SIGTERM");
+            });
+        }
+    }
+    shutdown(signal) {
+        if (this.shuttingDown) {
+            return;
+        }
+        this.shuttingDown = true;
+        if (signal !== "exit" &&
+            (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") {
+            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();
+    }
+}
+function closeResource(resource) {
+    try {
+        resource();
+    }
+    catch { }
+}
+function killProcess(proc, detached, signal) {
+    if (proc.pid === undefined || proc.killed) {
+        return;
+    }
+    try {
+        if (detached && process.platform !== "win32") {
+            process.kill(-proc.pid, signal);
+        }
+        else {
+            proc.kill(signal);
+        }
+    }
+    catch { }
+}
+export function installProcessSignalHandlers(run) {
+    for (const signal of ["SIGINT", "SIGTERM", "SIGHUP"]) {
+        process.on(signal, () => run.shutdown(signal));
+    }
+    process.on("exit", () => run.shutdown("exit"));
+    process.on("uncaughtException", error => {
+        console.error(error);
+        process.exitCode = 1;
+        run.shutdown("SIGTERM");
+    });
+}

package/dist-cli/published-cli.js ADDED Viewed

@@ -0,0 +1,73 @@
+/**
+ * Published launcher entry point for custom block authors. This file is the
+ * entry point for `ntn customblocks dev` and `npx @notionhq/custom-blocks-dev-shell`.
+ *
+ * The shared launcher orchestrates building the worker, reading its manifest,
+ * starting one Vite server per custom block, and owning the ports, output, and
+ * lifecycle. This entry point starts the dev shell and supplies the package's
+ * prebuilt shell adapter with the block registry and data sources.
+ *
+ * Other subcommands like `convert` exit before any dev shell machinery starts.
+ */
+import { existsSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { runConvert } from "./convert.js";
+import { readDataSources } from "./data-sources.js";
+import { launchDevShell } from "./dev-shell-launcher.js";
+import { copyPrebuiltDataSources } from "./prebuilt.js";
+import { serveUi } from "./serve-ui.js";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const createShellLaunch = async ({ args, plan, log }) => {
+    const distDir = resolve(__dirname, "..", "dist");
+    if (!existsSync(join(distDir, "index.html"))) {
+        throw new Error(`No prebuilt UI found at ${distDir}. This package was not assembled ` +
+            `correctly; reinstall it.`);
+    }
+    const prebuiltDir = resolve(__dirname, "..", "data");
+    let server;
+    try {
+        server = await serveUi(distDir, args.shellPort, {
+            blocks: plan.registry,
+            dataSources: plan.dataSources,
+            prebuiltFilenames: readDataSources(prebuiltDir).map(source => source.filename),
+        }, () => {
+            const written = copyPrebuiltDataSources(prebuiltDir, plan.dataDir);
+            if (written.length > 0) {
+                log(basename(plan.workerDir), `Added pre-built data sources: ${written.join(", ")}`);
+            }
+            return readDataSources(plan.dataDir);
+        });
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === "EADDRINUSE") {
+            throw new Error(`Port ${args.shellPort} is already in use. Stop whatever holds it ` +
+                `or rerun with --port <port> (and --block-base-port <port> for the ` +
+                `block servers).`);
+        }
+        throw error;
+    }
+    return {
+        processes: [],
+        resources: [() => server.close()],
+    };
+};
+async function main() {
+    const argv = process.argv.slice(2);
+    // One-shot subcommands return before any dev shell machinery starts.
+    if (argv[0] === "convert") {
+        await runConvert(argv.slice(1));
+        return;
+    }
+    await launchDevShell({
+        argv,
+        workerBaseDir: process.cwd(),
+        detectFromDir: process.cwd(),
+        createShellLaunch,
+    });
+}
+main().catch(error => {
+    console.error(error instanceof Error ? error.message : error);
+    process.exitCode = 1;
+});

package/dist-cli/utils.js CHANGED Viewed

@@ -24,3 +24,28 @@ 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 = () => { }) {
+    const takeValue = (name, index) => {
+        const value = argv[index];
+        if (value === undefined || value.startsWith("--")) {
+            throw new Error(`${name} requires a value.`);
+        }
+        return value;
+    };
+    for (let index = 0; index < argv.length; index++) {
+        const arg = argv[index];
+        const separator = arg.indexOf("=");
+        const name = separator === -1 ? arg : arg.slice(0, separator);
+        const handler = handlers[name];
+        if (handler === undefined) {
+            onUnknown(arg);
+            continue;
+        }
+        const value = separator === -1 ? takeValue(name, ++index) : arg.slice(separator + 1);
+        handler(value);
+    }
+}

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@notionhq/custom-blocks-dev-shell",
-  "version": "0.1.33",
+  "version": "0.1.35",
   "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",