@notionhq/custom-blocks-dev-shell 0.0.1

package/cli/worker-manifest.ts

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