@notionhq/custom-blocks-dev-shell 0.1.0 → 0.1.2

package/docs/data-sources.md

@@ -0,0 +1,72 @@
+# Dev-shell data sources
+
+Data sources come in kinds, marked by their `type`, and all live in the
+worker's `src/data/*.json` — one source per file, read at spin-up. The shell
+supports the following types today:
+
+- `worker` — hand-authored JSON files. This is how you give your blocks data,
+  and what this document describes.
+- `manual` — sources a user creates themselves in the shell.
+- `built-in` — sources we provide.
+
+
+## File format
+
+```json
+{
+	"type": "worker",
+	"key": "tasks",
+	"name": "Tasks",
+	"icon": "✅",
+	"schema": {
+		"title": { "name": "Title", "type": "title" },
+		"status": { "name": "Status", "type": "select" },
+		"dueDate": { "name": "Due date", "type": "date" },
+		"done": { "name": "Done", "type": "checkbox" }
+	},
+	"rows": [
+		{
+			"id": "tasks-1",
+			"title": "Ship the block",
+			"status": "In progress",
+			"dueDate": { "type": "date", "start_date": "2026-08-01" },
+			"done": false
+		}
+	]
+}
+```
+
+- `type` — the source's kind; `"worker"`, the only kind these files can
+  declare today, is the default.
+- `key` — what blocks bind against; make it match a `dataSources` key from
+  `worker.customBlock(...)` so properties auto-match. Defaults to the
+  filename.
+- `name` — the label shown in the shell sidebar. Defaults to `key`.
+- `icon` — optional emoji shown alongside the name.
+- `schema` — property key → `{ name, type }`. Use the same property keys and
+  types the block declares. Types: `title`, `rich_text`, `number`, `select`,
+  `multi_select`, `status`, `date`, `checkbox`, `url`, `email`,
+  `phone_number`, `people`, `files`, `relation`.
+- `rows` — each row needs a unique string `id`; property values live under
+  their schema keys.
+
+Value shapes by property type:
+
+| Type | Value |
+| --- | --- |
+| `title`, `rich_text`, `select`, `status`, `url`, `email`, `phone_number` | string |
+| `multi_select` | array of strings |
+| `number` | number |
+| `checkbox` | boolean |
+| `date` | `{ "type": "date", "start_date": "YYYY-MM-DD" }`; ranges and datetimes use `"daterange"` / `"datetime"` / `"datetimerange"` with `end_date`, `start_time`, `end_time` |
+| `people` | array of `{ "id": "...", "table": "notion_user" }` pointers |
+| `relation` | array of `{ "id": "...", "table": "block" }` pointers |
+| `files` | string (the host serializes file properties as text today) |
+
+## Validation
+
+Files are validated at spin-up, before they reach the shell UI. A malformed
+file fails the run with the file and problem named, e.g.
+`src/data/tasks.json: rows.0.id: Invalid key: Expected "id" but received undefined`.
+Omitted `key`/`name` fall back to the filename; omitted `schema`/`rows` to
+empty.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@notionhq/custom-blocks-dev-shell",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Local preview shell for Notion custom block workers.",
   "license": "MIT",
   "repository": {
@@ -17,14 +17,15 @@
   },
   "files": [
     "bin",
-    "cli",
     "dist",
+    "dist-cli",
+    "docs",
     "README.md"
   ],
   "dependencies": {
     "react": "^19.2.5",
     "react-dom": "^19.2.5",
-    "tsx": "^4.21.0",
+    "valibot": "^1.3.1",
     "@notionhq/custom-blocks": "0.1.0"
   },
   "devDependencies": {
@@ -40,7 +41,7 @@
   },
   "scripts": {
     "dev": "vite",
-    "build": "vite build",
+    "build": "vite build && tsc --project tsconfig.cli.json",
     "test": "vitest run",
     "typecheck": "tsc --noEmit && tsc --noEmit --project tsconfig.cli.json"
   }

package/cli/main.ts

@@ -1,293 +0,0 @@
-/**
- * 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

@@ -1,100 +0,0 @@
-/**
- * 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))
-	})
-}

package/cli/worker-manifest.ts

@@ -1,196 +0,0 @@
-/**
- * Extract a worker's manifest without deploying it, following the localhost
- * verification strategy: build the worker, then read the manifest off the
- * built module's default export. This is the one prerequisite the dev shell
- * needs before it can list a worker's blocks and data sources.
- *
- * The worker manifest is otherwise in-memory only (tied to `worker.ts` + cloud
- * build), so we materialize it under the worker's git-ignored `.dev-shell/` dir
- * (clearly a dev-shell artifact, not something the author maintains).
- * Regenerated on every spin-up.
- */
-
-import { execSync } from "node:child_process"
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs"
-import { dirname, resolve } from "node:path"
-import { pathToFileURL } from "node:url"
-
-/** One custom-block capability in the worker manifest. */
-export type WorkerBlockCapability = {
-	_tag: "custom_block"
-	key: string
-	config: {
-		source: { type: string; path: string; command?: string; output?: string }
-		manifest: {
-			version: number
-			dataSources: Record<
-				string,
-				{
-					name: string
-					description?: string
-					icon?: unknown
-					properties?: Record<string, { name: string; type: string }>
-				}
-			>
-		}
-	}
-}
-
-/** One worker-defined database in the manifest. */
-export type WorkerDatabaseEntry = {
-	key: string
-	config: {
-		type: string
-		initialTitle?: string
-		primaryKeyProperty?: string
-		schema?: {
-			properties?: Record<string, { type: string; [k: string]: unknown }>
-		}
-	}
-}
-
-export type WorkerManifest = {
-	sdkVersion?: string
-	databases: WorkerDatabaseEntry[]
-	pacers: { key: string; config: unknown }[]
-	capabilities: { _tag: string; key: string; config: unknown }[]
-}
-
-export const WORKER_MANIFEST_FILENAME = "worker_manifest.json"
-
-/**
- * Heuristic for the no-flag fallback: does `dir` look like a worker project?
- * True if it carries a worker deploy binding (`worker.json`/`workers.json`) or
- * depends on `@notionhq/workers`.
- */
-export function looksLikeWorkerDir(dir: string): boolean {
-	if (
-		existsSync(resolve(dir, "worker.json")) ||
-		existsSync(resolve(dir, "workers.json"))
-	) {
-		return true
-	}
-	const pkgPath = resolve(dir, "package.json")
-	if (!existsSync(pkgPath)) {
-		return false
-	}
-	try {
-		const pkg = JSON.parse(readFileSync(pkgPath, "utf-8")) as {
-			dependencies?: Record<string, string>
-			devDependencies?: Record<string, string>
-		}
-		return Boolean(
-			pkg.dependencies?.["@notionhq/workers"] ??
-				pkg.devDependencies?.["@notionhq/workers"],
-		)
-	} catch {
-		return false
-	}
-}
-
-/**
- * Walk up from `startDir` looking for a worker directory (see
- * `looksLikeWorkerDir`), so the shell can be launched from anywhere inside a
- * worker, not only its root. Stops once it reaches a git-repo boundary (a
- * `.git` at the current level, checked after the worker test) or the filesystem
- * root — it should never escape the project the user is in.
- */
-export function findWorkerDir(startDir: string): string | undefined {
-	let current = resolve(startDir)
-	while (true) {
-		if (looksLikeWorkerDir(current)) {
-			return current
-		}
-		if (existsSync(resolve(current, ".git"))) {
-			return undefined
-		}
-		const parent = dirname(current)
-		if (parent === current) {
-			return undefined
-		}
-		current = parent
-	}
-}
-
-/** The custom-block capabilities in a manifest, narrowed by `_tag`. */
-export function blockCapabilities(
-	manifest: WorkerManifest,
-): WorkerBlockCapability[] {
-	return manifest.capabilities.filter(
-		(capability): capability is WorkerBlockCapability =>
-			capability._tag === "custom_block",
-	)
-}
-
-function isManifestShape(value: unknown): value is WorkerManifest {
-	return (
-		typeof value === "object" &&
-		value !== null &&
-		Array.isArray((value as WorkerManifest).capabilities)
-	)
-}
-
-/**
- * Build the worker in `workerDir` and read its manifest off the built default
- * export. Mirrors the deploy path (build → read the built module) rather than
- * importing TypeScript source, so what the dev shell sees matches what a deploy
- * would produce.
- */
-export async function extractWorkerManifest(
-	workerDir: string,
-	options: { build?: boolean } = {},
-): Promise<WorkerManifest> {
-	const root = resolve(workerDir)
-	if (!existsSync(resolve(root, "package.json"))) {
-		throw new Error(`No package.json found in worker directory: ${root}`)
-	}
-
-	if (options.build !== false) {
-		execSync("npm run build", { cwd: root, stdio: "inherit" })
-	}
-
-	const entry = resolve(root, "dist/index.js")
-	if (!existsSync(entry)) {
-		throw new Error(
-			`Built worker entry not found at ${entry}. The worker's build must emit dist/index.js.`,
-		)
-	}
-
-	const mod = (await import(pathToFileURL(entry).href)) as {
-		default?: { manifest?: unknown; capabilities?: unknown }
-	}
-	const worker = mod.default
-	if (worker === undefined) {
-		throw new Error(`Built worker at ${entry} has no default export.`)
-	}
-
-	// Read the built worker's manifest, falling back to a bare capabilities array
-	// (per the localhost verification doc's `w.manifest || w.capabilities`).
-	const raw = worker.manifest ?? worker.capabilities
-	if (isManifestShape(raw)) {
-		return raw
-	}
-	if (Array.isArray(raw)) {
-		return { databases: [], pacers: [], capabilities: raw }
-	}
-	throw new Error(
-		`Built worker at ${entry} exposed no usable manifest (expected .manifest or .capabilities).`,
-	)
-}
-
-/**
- * Extract the worker manifest and write it to `.dev-shell/worker_manifest.json`
- * inside the worker (a git-ignored dev-shell artifact dir). Returns the parsed
- * manifest and the path written.
- */
-export async function generateWorkerManifest(
-	workerDir: string,
-	options: { build?: boolean } = {},
-): Promise<{ manifest: WorkerManifest; manifestPath: string }> {
-	const manifest = await extractWorkerManifest(workerDir, options)
-	const dir = resolve(workerDir, ".dev-shell")
-	mkdirSync(dir, { recursive: true })
-	const manifestPath = resolve(dir, WORKER_MANIFEST_FILENAME)
-	writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`)
-	return { manifest, manifestPath }
-}