@notionhq/custom-blocks-dev-shell 0.0.1

package/README.md

@@ -0,0 +1,30 @@
+# Notion custom blocks dev shell
+
+A local preview shell for Notion custom block workers. It builds your worker,
+reads the manifest declared by your `worker.customBlock(...)` calls, serves each
+block with your project's own Vite, and renders them in a mock Notion host with
+sample data sources you can bind against.
+
+## Usage
+
+From anywhere inside your worker project:
+
+```bash
+npx @notionhq/custom-blocks-dev-shell
+```
+
+Then open http://localhost:9873.
+
+Options:
+
+- `--worker <dir>` — point at a worker directory explicitly instead of
+  detecting one from the current directory.
+- `--port <port>` — serve the shell UI somewhere other than 9873.
+- `--block-base-port <port>` — first port handed to the per-block dev servers
+  (default 9876; blocks count up from there).
+
+## Requirements
+
+- Node.js >= 20.19 (per Vite's own minimum for dev servers).
+- The worker's dependencies installed (`npm install`), including `vite` and a
+  build script that emits `dist/index.js`.

package/bin/cli.js

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+import { spawnSync } from "node:child_process"
+import { createRequire } from "node:module"
+import { dirname, resolve } from "node:path"
+import { fileURLToPath } from "node:url"
+
+const require = createRequire(import.meta.url)
+let tsxBin
+try {
+	const tsxPkg = require.resolve("tsx/package.json")
+	tsxBin = resolve(dirname(tsxPkg), "dist/cli.mjs")
+} catch {
+	process.stderr.write(
+		"✗ Could not locate the bundled tsx runtime. Reinstall the dev shell package.\n",
+	)
+	process.exit(1)
+}
+
+const entryPath = resolve(
+	dirname(fileURLToPath(import.meta.url)),
+	"..",
+	"cli",
+	"main.ts",
+)
+const result = spawnSync(
+	process.execPath,
+	[tsxBin, entryPath, ...process.argv.slice(2)],
+	{
+		stdio: "inherit",
+		env: process.env,
+	},
+)
+
+if (result.error) {
+	process.stderr.write(`✗ Failed to start the dev shell: ${result.error}\n`)
+}
+process.exit(result.status ?? 1)

package/cli/block-server.ts

@@ -0,0 +1,108 @@
+/**
+ * Per-block Vite server plumbing shared by the repo dev script
+ * (`scripts/dev.ts`) and the published dev-shell CLI (`cli/main.ts`).
+ */
+
+import { existsSync, mkdirSync, writeFileSync } from "node:fs"
+import { relative, resolve } from "node:path"
+import type { WorkerBlockCapability } from "./worker-manifest"
+
+/** First port handed to per-block Vite servers; blocks count up from here. */
+export const BLOCK_BASE_PORT = 9876
+
+/** Port the dev-shell-2 UI is served on. */
+export const SHELL_2_PORT = 9873
+
+/** One block entry handed to the dev-shell-2 UI. */
+export type BlockRegistryEntry = {
+	key: string
+	name: string
+	url: string
+}
+
+/** The registry for a worker's blocks, assuming sequential port assignment. */
+export function buildBlockRegistry(
+	blocks: readonly WorkerBlockCapability[],
+	basePort: number = BLOCK_BASE_PORT,
+): BlockRegistryEntry[] {
+	return blocks.map((capability, index) => ({
+		key: capability.key,
+		name: capability.key,
+		url: `http://localhost:${basePort + index}/`,
+	}))
+}
+
+/** Import specifier from `fromDir` to `toPath`, POSIX-style for ESM. */
+function relativeImport(fromDir: string, toPath: string): string {
+	const rel = relative(fromDir, toPath).split(/[\\/]/).join("/")
+	return rel.startsWith(".") ? rel : `./${rel}`
+}
+
+/**
+ * Write a per-block Vite config wrapper into the worker's `.dev-shell/` dir. It
+ * re-exports the block's own config (keeping its plugins) but pins `root` to the
+ * block and `cacheDir` to a block-specific dir, so concurrently-run block
+ * servers don't collide in the worker's shared `node_modules/.vite`. It also
+ * serves `/custom_blocks.json` from the block's slice of the worker manifest —
+ * worker-backed blocks carry no manifest file of their own, so the wrapper
+ * plays the part production infra does and answers the SDK's manifest fetch
+ * from the worker's declaration. Returns the wrapper path for `vite --config`.
+ */
+export function writeBlockViteConfig(
+	workerDir: string,
+	blockDir: string,
+	capability: WorkerBlockCapability,
+): string {
+	const key = capability.key
+	const dir = resolve(workerDir, ".dev-shell")
+	mkdirSync(dir, { recursive: true })
+	const blockConfig = resolve(blockDir, "vite.config.ts")
+	const toRoot = relativeImport(dir, blockDir)
+	const toCache = relativeImport(
+		dir,
+		resolve(workerDir, "node_modules/.vite", key),
+	)
+	const baseImport = existsSync(blockConfig)
+		? `import base from "${relativeImport(dir, blockConfig)}"`
+		: `const base = {}`
+	const file = resolve(dir, `${key}.mjs`)
+	writeFileSync(
+		file,
+		`import { fileURLToPath } from "node:url"
+${baseImport}
+
+const here = p => fileURLToPath(new URL(p, import.meta.url))
+const resolved =
+	typeof base === "function"
+		? await base({ command: "serve", mode: "development" })
+		: base
+
+const manifest = ${JSON.stringify(JSON.stringify(capability.config.manifest))}
+
+// enforce: "pre" registers this middleware ahead of the SDK vite plugin's,
+// which would otherwise 404 the path (no manifest file exists in the block).
+const serveWorkerManifest = {
+	name: "dev-shell:worker-block-manifest",
+	enforce: "pre",
+	configureServer(server) {
+		server.middlewares.use((req, res, next) => {
+			if (req.url?.split("?", 1)[0] !== "/custom_blocks.json") {
+				next()
+				return
+			}
+			res.setHeader("Content-Type", "application/json")
+			res.end(manifest)
+		})
+	},
+}
+
+export default {
+	...resolved,
+	root: here("${toRoot}"),
+	cacheDir: here("${toCache}"),
+	plugins: [serveWorkerManifest, ...(resolved.plugins ?? [])],
+}
+`,
+	)
+	return file
+}

package/cli/main.ts

@@ -0,0 +1,293 @@
+/**
+ * Entry point for the published dev-shell CLI (`npx`-run from a worker
+ * project). Mirrors the worker mode of the repo's `scripts/dev.ts`: build the
+ * worker, extract its manifest, serve one Vite dev server per custom block
+ * (using the worker's own Vite install), and serve the prebuilt dev-shell-2 UI
+ * with the block registry injected at runtime.
+ */
+
+import { spawn } from "node:child_process"
+import { existsSync, readFileSync } from "node:fs"
+import { createRequire } from "node:module"
+import { basename, dirname, join, resolve } from "node:path"
+import { fileURLToPath } from "node:url"
+import {
+	BLOCK_BASE_PORT,
+	buildBlockRegistry,
+	SHELL_2_PORT,
+	writeBlockViteConfig,
+} from "./block-server"
+import { serveUi } from "./serve-ui"
+import {
+	blockCapabilities,
+	findWorkerDir,
+	generateWorkerManifest,
+} from "./worker-manifest"
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+
+const dim = "\x1b[2m"
+const bold = "\x1b[1m"
+const cyan = "\x1b[36m"
+const reset = "\x1b[0m"
+const label = (name: string) => `${cyan}[${name}]${reset}`
+
+type CliArgs = {
+	worker: string | undefined
+	shellPort: number
+	blockBasePort: number
+}
+
+function parseCliArgs(argv: readonly string[]): CliArgs {
+	const args: CliArgs = {
+		worker: undefined,
+		shellPort: SHELL_2_PORT,
+		blockBasePort: BLOCK_BASE_PORT,
+	}
+	const takeValue = (name: string, index: number): string => {
+		const value = argv[index]
+		if (value === undefined || value.startsWith("--")) {
+			throw new Error(`${name} requires a value.`)
+		}
+		return value
+	}
+	const takePort = (name: string, raw: string): number => {
+		const port = Number(raw)
+		if (!Number.isInteger(port) || port <= 0 || port > 65535) {
+			throw new Error(`${name} requires a port number, got "${raw}".`)
+		}
+		return port
+	}
+	for (let index = 0; index < argv.length; index++) {
+		const arg = argv[index]
+		if (arg === "--worker") {
+			args.worker = takeValue("--worker", ++index)
+		} else if (arg.startsWith("--worker=")) {
+			args.worker = arg.slice("--worker=".length)
+			if (args.worker.length === 0) {
+				throw new Error("--worker requires a path to a worker directory.")
+			}
+		} else if (arg === "--port") {
+			args.shellPort = takePort("--port", takeValue("--port", ++index))
+		} else if (arg.startsWith("--port=")) {
+			args.shellPort = takePort("--port", arg.slice("--port=".length))
+		} else if (arg === "--block-base-port") {
+			args.blockBasePort = takePort(
+				"--block-base-port",
+				takeValue("--block-base-port", ++index),
+			)
+		} else if (arg.startsWith("--block-base-port=")) {
+			args.blockBasePort = takePort(
+				"--block-base-port",
+				arg.slice("--block-base-port=".length),
+			)
+		}
+	}
+	return args
+}
+
+function resolveWorkerDir(workerArg: string | undefined): string {
+	if (workerArg !== undefined) {
+		return resolve(process.cwd(), workerArg)
+	}
+	const detected = findWorkerDir(process.cwd())
+	if (detected !== undefined) {
+		console.log(`Detected a worker at ${detected}.`)
+		return detected
+	}
+	throw new Error(
+		"No worker found: run from inside a worker directory, or pass --worker <dir>.",
+	)
+}
+
+/**
+ * The worker's own Vite binary. Blocks are served with the worker's Vite (and
+ * plugins) rather than anything bundled here, matching how the block builds in
+ * production.
+ */
+function resolveViteBin(workerDir: string): string {
+	let vitePkgPath: string
+	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")) as {
+		bin?: string | Record<string, string>
+	}
+	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)
+}
+
+const procs: ReturnType<typeof spawn>[] = []
+
+async function main() {
+	const cliArgs = parseCliArgs(process.argv.slice(2))
+	const workerDir = resolveWorkerDir(cliArgs.worker)
+	if (!existsSync(resolve(workerDir, "node_modules"))) {
+		throw new Error(
+			`No node_modules in ${workerDir}. Install the worker's dependencies first ` +
+				`(e.g. \`npm install\`), then rerun.`,
+		)
+	}
+
+	console.log(`${label(basename(workerDir))} Extracting worker manifest...`)
+	const { manifest, manifestPath } = await generateWorkerManifest(workerDir)
+	console.log(`${label(basename(workerDir))} Wrote ${manifestPath}`)
+	const blocks = blockCapabilities(manifest)
+	if (blocks.length === 0) {
+		// Not an error — start the shell anyway; it shows "None" under Blocks.
+		console.log(
+			`${label(basename(workerDir))} Worker declares no custom blocks.`,
+		)
+	}
+
+	if (
+		blocks.length > 0 &&
+		cliArgs.shellPort >= cliArgs.blockBasePort &&
+		cliArgs.shellPort < cliArgs.blockBasePort + blocks.length
+	) {
+		throw new Error(
+			`--port ${cliArgs.shellPort} collides with the block server ports ` +
+				`(${cliArgs.blockBasePort}–${cliArgs.blockBasePort + blocks.length - 1}); ` +
+				`pick a port outside that range or move --block-base-port.`,
+		)
+	}
+
+	const viteBin = blocks.length > 0 ? resolveViteBin(workerDir) : undefined
+	const registry = buildBlockRegistry(blocks, cliArgs.blockBasePort)
+
+	for (const [index, capability] of blocks.entries()) {
+		const blockDir = resolve(workerDir, capability.config.source.path)
+		const configFile = writeBlockViteConfig(workerDir, blockDir, capability)
+		const port = cliArgs.blockBasePort + index
+		const proc = spawn(
+			process.execPath,
+			[
+				viteBin as string,
+				"--config",
+				configFile,
+				"--port",
+				String(port),
+				"--strictPort",
+			],
+			{
+				cwd: workerDir,
+				stdio: ["ignore", "ignore", "inherit"],
+				// Process groups (and negative-PID kills) are POSIX-only; on
+				// Windows children are killed individually in shutdown().
+				detached: process.platform !== "win32",
+			},
+		)
+		proc.on("exit", code => {
+			if (shuttingDown || code === 0 || code === null) {
+				return
+			}
+			console.error(
+				`${label(capability.key)} dev server exited with code ${code}`,
+			)
+			process.exitCode = code
+			shutdown("SIGTERM")
+		})
+		procs.push(proc)
+	}
+
+	// The published layout is dist/ next to cli/; index.html must be prebuilt.
+	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.`,
+		)
+	}
+	try {
+		await serveUi(distDir, cliArgs.shellPort, {
+			mode: "worker",
+			blocks: registry,
+		})
+	} catch (error) {
+		const code = (error as NodeJS.ErrnoException).code
+		if (code === "EADDRINUSE") {
+			throw new Error(
+				`Port ${cliArgs.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
+	}
+
+	console.log("")
+	console.log(`${bold}Dev shell${reset}`)
+	console.log(
+		`  ${label("dev-shell")} ${dim}http://localhost:${cliArgs.shellPort}${reset}`,
+	)
+	if (blocks.length > 0) {
+		console.log("")
+		console.log(`${bold}Blocks${reset}`)
+		for (const [index, entry] of registry.entries()) {
+			console.log(
+				`  ${label(entry.key)} ${dim}http://localhost:${cliArgs.blockBasePort + index}${reset}`,
+			)
+		}
+	}
+	console.log("")
+}
+
+function killProc(p: ReturnType<typeof spawn>, signal: NodeJS.Signals) {
+	if (p.pid === undefined || p.killed) {
+		return
+	}
+	try {
+		if (process.platform === "win32") {
+			p.kill(signal)
+		} else {
+			process.kill(-p.pid, signal)
+		}
+	} catch {}
+}
+
+let shuttingDown = false
+function shutdown(signal: NodeJS.Signals | "exit") {
+	if (shuttingDown) {
+		return
+	}
+	shuttingDown = true
+	if (signal !== "exit") {
+		console.log(`\n${dim}Shutting down...${reset}`)
+	}
+	for (const p of procs) {
+		killProc(p, "SIGTERM")
+	}
+	setTimeout(() => {
+		for (const p of procs) {
+			killProc(p, "SIGKILL")
+		}
+		// Preserve a failure exit code set before shutdown (startup errors,
+		// crashed block servers); plain signal shutdowns still exit 0.
+		process.exit(process.exitCode ?? 0)
+	}, 1500).unref()
+}
+
+for (const signal of ["SIGINT", "SIGTERM", "SIGHUP"] as const) {
+	process.on(signal, () => shutdown(signal))
+}
+process.on("exit", () => shutdown("exit"))
+process.on("uncaughtException", err => {
+	console.error(err)
+	process.exitCode = 1
+	shutdown("SIGTERM")
+})
+
+main().catch(err => {
+	console.error(err instanceof Error ? err.message : err)
+	process.exitCode = 1
+	shutdown("SIGTERM")
+})

package/cli/serve-ui.ts

@@ -0,0 +1,100 @@
+/**
+ * Dependency-free static server for the prebuilt dev-shell-2 UI (`dist/`).
+ *
+ * The published UI is a plain Vite build, so the block registry can't ride in
+ * through build-time `define` globals the way it does under `scripts/dev.ts`.
+ * Instead, this server injects a `window.__DEV_SHELL_2_CONFIG__` script into
+ * `index.html` as it is served; `src/helpers/templates.ts` prefers that global
+ * over the baked-in defines.
+ */
+
+import { readFileSync } from "node:fs"
+import { createServer, type Server } from "node:http"
+import { extname, join, normalize, resolve, sep } from "node:path"
+import type { BlockRegistryEntry } from "./block-server"
+
+export type DevShellRuntimeConfig = {
+	mode: "worker"
+	blocks: BlockRegistryEntry[]
+}
+
+const CONTENT_TYPES: Record<string, string> = {
+	".html": "text/html; charset=utf-8",
+	".js": "text/javascript; charset=utf-8",
+	".mjs": "text/javascript; charset=utf-8",
+	".css": "text/css; charset=utf-8",
+	".json": "application/json; charset=utf-8",
+	".svg": "image/svg+xml",
+	".png": "image/png",
+	".ico": "image/x-icon",
+	".woff": "font/woff",
+	".woff2": "font/woff2",
+	".map": "application/json; charset=utf-8",
+}
+
+/** `index.html` with the runtime config injected ahead of the bundle script. */
+function injectConfig(html: string, config: DevShellRuntimeConfig): string {
+	const tag = `<script>window.__DEV_SHELL_2_CONFIG__ = ${JSON.stringify(config)}</script>`
+	if (html.includes("<head>")) {
+		return html.replace("<head>", `<head>\n\t\t${tag}`)
+	}
+	return `${tag}\n${html}`
+}
+
+/**
+ * Serve `distDir` on `port`. Unknown extensionless paths fall back to
+ * `index.html`. Rejects on listen errors (e.g. the port is taken).
+ */
+export function serveUi(
+	distDir: string,
+	port: number,
+	config: DevShellRuntimeConfig,
+): Promise<Server> {
+	const dist = resolve(distDir)
+	const indexHtml = injectConfig(
+		readFileSync(join(dist, "index.html"), "utf-8"),
+		config,
+	)
+
+	const server = createServer((req, res) => {
+		let path: string
+		try {
+			path = normalize(decodeURIComponent(req.url?.split("?", 1)[0] ?? "/"))
+		} catch {
+			res.writeHead(400)
+			res.end()
+			return
+		}
+		const filePath = join(dist, path)
+		if (!filePath.startsWith(dist + sep) && filePath !== dist) {
+			res.writeHead(403)
+			res.end()
+			return
+		}
+
+		const ext = extname(filePath)
+		if (path === "/" || path === `${sep}index.html` || ext === "") {
+			res.writeHead(200, { "Content-Type": CONTENT_TYPES[".html"] })
+			res.end(indexHtml)
+			return
+		}
+
+		try {
+			const body = readFileSync(filePath)
+			res.writeHead(200, {
+				"Content-Type": CONTENT_TYPES[ext] ?? "application/octet-stream",
+			})
+			res.end(body)
+		} catch {
+			res.writeHead(404)
+			res.end()
+		}
+	})
+
+	return new Promise((resolvePromise, reject) => {
+		server.once("error", reject)
+		// Loopback only: every response embeds the worker's block registry, and
+		// the per-block Vite servers are localhost-only too.
+		server.listen(port, "127.0.0.1", () => resolvePromise(server))
+	})
+}