create-ncblock 0.0.16 → 0.0.18

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "create-ncblock",
-	"version": "0.0.16",
+	"version": "0.0.18",
 	"description": "Create a Notion custom view block project.",
 	"type": "module",
 	"bin": {

package/scripts/init.ts

@@ -1,6 +1,6 @@
 import { execSync, spawnSync } from "child_process"
 import { existsSync, mkdirSync, readdirSync, writeFileSync } from "fs"
-import { basename, dirname, resolve } from "path"
+import { dirname, resolve } from "path"
 import {
 	clearScreenDown,
 	createInterface,
@@ -9,6 +9,12 @@ import {
 	moveCursor,
 } from "readline"
 import { fileURLToPath } from "url"
+import {
+	type Classified,
+	classifyPositionalId,
+	EXIT_USER_ID_MISTAKE,
+} from "./utils/classifyId"
+import { resolveInitArgs } from "./utils/resolveInitArgs"
 import {
 	getTemplateByName,
 	getTemplates,
@@ -18,8 +24,8 @@ import {
 
 /**
  * Seed `.notion/target.json` with whatever's known at scaffold time. Empty
- * defaults are intentional — subsequent commands (`manifest pull`, `connect`,
- * `deploy`) all merge into this file.
+ * defaults are intentional — subsequent `ncblock connect` / `deploy` calls
+ * merge into this file.
  */
 type InitialTarget = {
 	env: string
@@ -57,6 +63,10 @@ function writeInitialTarget(
  *
  * Env is sourced from target.json (written by writeInitialTarget before
  * any ncblock call) — no need to thread ENV through the spawn.
+ *
+ * Exits init immediately on `EXIT_USER_ID_MISTAKE` so we don't fall through
+ * to "Ready! Next steps:" with a broken target.json. Any other non-zero exit
+ * is thrown so the caller's try/catch can suppress without forwarding stderr.
  */
 function runNcblock(dest: string, args: string[]): void {
 	const result = spawnSync(
@@ -64,9 +74,10 @@ function runNcblock(dest: string, args: string[]): void {
 		[resolve(dest, "node_modules/ncblock/bin/cli/cli.js"), ...args],
 		{ cwd: dest, stdio: "inherit" },
 	)
+	if (result.status === EXIT_USER_ID_MISTAKE) {
+		process.exit(EXIT_USER_ID_MISTAKE)
+	}
 	if (result.status !== 0) {
-		// Child already printed a user-friendly message; throw so the caller's
-		// try/catch can suppress without us having to forward stderr.
 		throw new Error(
 			`ncblock ${args.join(" ")} exited with code ${result.status}`,
 		)
@@ -563,18 +574,32 @@ async function main() {
 		args.install as boolean | undefined,
 	)
 
-	// Ask for the database URL/ID upfront — alongside the other prompts. The
-	// prompt itself only fires when we'll actually install (no manifest pull
-	// otherwise), but --collection is always honored.
-	const collectionAnswer =
-		(args.collection as string | undefined) ??
-		(installDeps
+	// Precedence: --collection > --block/positional > prompt. Classification
+	// downstream walks a positional block/view ID up to its parent database.
+	const blockIdArg = args.block as string | undefined
+	const promptedCollection =
+		args.collection === undefined && blockIdArg === undefined && installDeps
 			? (await ask("Database URL/ID (enter to skip):", "skip")).trim()
-			: "skip")
-	const collectionId =
-		collectionAnswer && collectionAnswer !== "skip"
-			? collectionAnswer
 			: undefined
+	const collectionOverride =
+		(args.collection as string | undefined) ??
+		(promptedCollection && promptedCollection !== "skip"
+			? promptedCollection
+			: undefined)
+
+	const resolved = resolveInitArgs({
+		collection: collectionOverride,
+		block: blockIdArg,
+		envBlockId: process.env.BLOCK_ID,
+		envName: process.env.ENV,
+	})
+	const classified: Classified | null = resolved.idToClassify
+		? classifyPositionalId(resolved.idToClassify, resolved.env)
+		: null
+	// Explicit --collection wins over classification; classify normalizes
+	// the positional input to a dashed UUID and falls back to the raw value.
+	const blockId = classified?.blockId ?? resolved.blockId
+	const databaseId = resolved.databaseId ?? classified?.databaseId
 
 	printSummary({
 		dest,
@@ -615,20 +640,19 @@ async function main() {
 		step("Initialized git repo")
 	}
 
-	const blockId =
-		(args.block as string | undefined) || process.env.BLOCK_ID || undefined
-	const envName = process.env.ENV
-
-	// Always seed .notion/target.json so every project starts in a known
-	// state. env / block_id are populated from what we have; data_sources
-	// gets filled in by `manifest pull` if it runs.
-	writeInitialTarget(dest, { env: envName, blockId })
+	writeInitialTarget(dest, { env: resolved.env, blockId })
 	step(`Seeded .notion/target.json`)
+	if (classified?.kind === "view") {
+		console.log(
+			`    ${c.dim}(view ID resolved — using as block id, database ${databaseId ?? "(none)"})${c.reset}`,
+		)
+	}
 
+	let connected = false
 	if (installDeps) {
 		// Close the readline interface before shelling out — otherwise it
 		// holds onto stdin/stdout and the inherited stdio in child processes
-		// gets buffered, which makes pull-manifest output land out of order.
+		// gets buffered, which makes ncblock output land out of order.
 		closePromptInterface()
 
 		console.log("")
@@ -636,27 +660,16 @@ async function main() {
 		execSync(`${pm} ${installArgs}`, { cwd: dest, stdio: "inherit" })
 		step("Installed dependencies")
 
-		// `manifest pull` resolves a database / data source / collection_view
-		// block URL to a manifest entry AND merges the resolved data_source_id
-		// into target.json's data_sources. Then `connect` (no flags needed —
-		// reads everything from target.json) PATCHes the block if one's set.
-		let pulled = false
-		if (collectionId) {
+		if (databaseId) {
 			console.log("")
 			try {
-				runNcblock(dest, ["manifest", "pull", collectionId])
-				step("Updated custom_blocks.json from collection schema")
-				pulled = true
-			} catch {
-				// manifest pull already printed a user-friendly message
-			}
-		}
-
-		if (pulled && blockId) {
-			console.log("")
-			try {
-				runNcblock(dest, ["connect"])
-				step("Wired block bindings (.notion/target.json + PATCH)")
+				runNcblock(dest, ["connect", databaseId, "--quiet"])
+				step(
+					blockId
+						? "Wired block bindings (custom_blocks.json + .notion/target.json + PATCH)"
+						: "Recorded data source in custom_blocks.json + .notion/target.json",
+				)
+				connected = true
 			} catch {
 				// connect already printed a user-friendly message
 			}
@@ -674,13 +687,21 @@ async function main() {
 	}
 	console.log(`  ${pm} run build`)
 	if (deployCommand) {
-		console.log(`  ${deployCommand}\n`)
+		console.log(`  ${deployCommand}`)
 	} else {
 		console.log(
-			`\n  Then, go back to the instructions in Notion and paste the ${c.bold}ntn deploy${c.reset} command.\n`,
+			`\n  Then, go back to the instructions in Notion and paste the ${c.bold}ntn deploy${c.reset} command.`,
 		)
 	}
 
+	if (installDeps && !connected) {
+		console.log(
+			`\n  ${c.yellow}No data source connected yet.${c.reset} To wire one up:`,
+		)
+		console.log(`    npx ncblock connect <database-url-or-id>`)
+	}
+	console.log("")
+
 	closePromptInterface()
 }
 

package/scripts/scaffold-assets/AGENTS.md

@@ -2,6 +2,16 @@
 
 A **Notion custom view** — a sandboxed `<iframe>` rendered inside a Notion block. The iframe is the entire viewport; the only channel to the host is a `postMessage` bridge wrapped by `ncblock`.
 
+## Connecting to a Notion database
+
+If `custom_blocks.json` or `.notion/target.json` doesn't yet reference a datasource, ask the user if they want to connect a database by url or id, then run:
+
+```bash
+npx ncblock connect <database-url-or-id>
+```
+
+That writes `custom_blocks.json`, `.notion/target.json`, and PATCHes any blocks already listed there. Discover other commands with `npx ncblock --help`.
+
 ## Talking to the host
 
 - Always use the React hooks from `ncblock`. Never call `window.parent.postMessage` directly — the SDK owns the protocol.
@@ -32,7 +42,6 @@ Hooks at a glance:
 
 - Mount into `<div id="root">` — `useCustomBlockAutoResize` looks for that exact id.
 - `custom_blocks.json` at the project root defines the data contract. The SDK's Vite plugin serves it in dev; `ntn` bundles it into the deploy.
-- `custom_blocks.json` is the **portable contract** — no IDs. `.notion/target.json` holds the per-deploy IDs (block IDs, data-source IDs, resolved property IDs) and is committed alongside it.
 
 ## Previewing during development
 
@@ -45,23 +54,6 @@ Two options:
    cd custom && pnpm install && pnpm run dev:shell   # http://localhost:9875
    ```
 
-## Connecting to Notion
-
-`ncblock` cli provides helpers to wire a scaffolded project to a Notion block and data source. Wirings are saved to `.notion/target.json`. Check the output of the cli for latest syntax instead of copying these commands verbatim.
-
-```bash
-# Pull a schema manifest from a Notion database into custom_blocks.json
-npx ncblock manifest pull <db-id-or-url>
-
-# Connect a local project to a Notion block and/or data source.
-npx ncblock connect
-
-# Deploy a dist/ directory to a block.
-npx ncblock deploy
-```
-
-Templates will often already have some of these set in `.notion/target.json`.
-
 ## Where to look next
 
 - `node_modules/ncblock/README.md` — landing page with a TOC into the per-category docs below.

package/scripts/utils/classifyId.ts

@@ -0,0 +1,227 @@
+import { execSync } from "node:child_process"
+
+/** Sentinel exit code for "user pasted the wrong kind of ID" errors. */
+export const EXIT_USER_ID_MISTAKE = 2
+
+const MAX_PARENT_HOPS = 5
+
+const YELLOW = "\x1b[33m"
+const RESET = "\x1b[0m"
+
+export type Classified = {
+	kind: "block" | "view"
+	/** What we'll write to `target.json#block_id`. Equals the user's input. */
+	blockId: string
+	/** What we'll pass to `ncblock connect` (if known). */
+	databaseId?: string
+}
+
+/**
+ * Resolve the user's positional ID into `{ blockId, databaseId }` BEFORE
+ * scaffolding, so bad inputs don't leave a half-written project on disk and
+ * good inputs already know which DB to pull from.
+ *
+ * - `/v1/databases/<id>` succeeds → user pasted a database ID into the
+ *   block-ID slot. Fail-fast.
+ * - `/v1/blocks/<id>` succeeds → it's a block. `blockId` is the input;
+ *   `databaseId` is walked from `block.parent` (database_id parent, or
+ *   data_source parent, or recurse through block/page parents).
+ * - `/v1/views/<id>` succeeds → it's a view (Notion URL `?v=<id>` form).
+ *   `blockId` = input (the view ID is the custom_block ID for the deploy
+ *   target); `databaseId` = `view.parent.database_id`.
+ * - All three 404 → wrong workspace. Fail-fast.
+ * - Any non-404 failure → surface ntn's stderr and exit with its status,
+ *   instead of misclassifying as "not in your workspace."
+ *
+ * Best-effort: if `ntn` isn't on PATH, returns `null` (with a warning logged
+ * by `isNtnAvailable`) — `ncblock connect`'s downstream errors will surface
+ * real issues.
+ */
+export function classifyPositionalId(
+	rawId: string,
+	env: string,
+): Classified | null {
+	const id = formatDashedUuid(rawId)
+
+	if (!isNtnAvailable()) {
+		return null
+	}
+
+	const dbResult = tryNtnApi(env, `/v1/databases/${id}`)
+	if (dbResult.ok && isDatabaseShape(dbResult.body)) {
+		bailUserInput(
+			`${id} is a database id, please paste the block id or view id`,
+		)
+	}
+
+	const blockResult = tryNtnApi(env, `/v1/blocks/${id}`)
+	if (blockResult.ok) {
+		return {
+			kind: "block",
+			blockId: id,
+			databaseId: walkBlockToDatabase(blockResult.body, env, 0),
+		}
+	}
+
+	const viewResult = tryNtnApi(env, `/v1/views/${id}`)
+	if (viewResult.ok) {
+		const v = viewResult.body as
+			| { parent?: { database_id?: string } }
+			| undefined
+		return { kind: "view", blockId: id, databaseId: v?.parent?.database_id }
+	}
+
+	// Every probe failed. If any returned a non-404, show ntn's actual stderr
+	// — saying "not in your workspace" would mislead the user when the real
+	// issue is e.g. a 400 validation error. Only the all-404 case gets the
+	// wrong-workspace nudge.
+	const firstError = [dbResult, blockResult, viewResult].find(r => r.error)
+	if (firstError) {
+		process.stderr.write(firstError.error ?? "")
+		process.exit(firstError.status ?? 1)
+	}
+
+	bailUserInput(
+		`${id} doesn't look like a valid id for your workspace. Ensure you're logged in to the right workspace with \`${loginCommandHint(env)}\`.`,
+	)
+}
+
+/**
+ * Walk up a block's parent chain looking for an enclosing database. The
+ * common case is `parent.type === "database_id"` (one hop), but blocks can
+ * also be children of pages or other blocks, so we recurse up to
+ * MAX_PARENT_HOPS.
+ */
+function walkBlockToDatabase(
+	block: unknown,
+	env: string,
+	depth: number,
+): string | undefined {
+	if (depth >= MAX_PARENT_HOPS) {
+		return undefined
+	}
+	const parent = (block as { parent?: Record<string, unknown> } | undefined)
+		?.parent
+	const parentType = typeof parent?.type === "string" ? parent.type : undefined
+	if (!parent || !parentType) {
+		return undefined
+	}
+
+	const parentId = parent[parentType]
+	if (typeof parentId !== "string") {
+		return undefined
+	}
+
+	switch (parentType) {
+		case "database_id":
+			return parentId
+		case "data_source_id": {
+			const ds = tryNtnApi(env, `/v1/data_sources/${parentId}`)
+			if (!ds.ok) {
+				return undefined
+			}
+			// TODO(custom-blocks): validate the data source response shape with
+			// a proper type guard instead of casting.
+			const dbId = (
+				ds.body as { parent?: { database_id?: string } } | undefined
+			)?.parent?.database_id
+			return dbId
+		}
+		case "block_id":
+		case "page_id": {
+			const parentBlock = tryNtnApi(env, `/v1/blocks/${parentId}`)
+			return parentBlock.ok
+				? walkBlockToDatabase(parentBlock.body, env, depth + 1)
+				: undefined
+		}
+		default:
+			return undefined
+	}
+}
+
+function isNtnAvailable(): boolean {
+	try {
+		execSync("ntn --version", { stdio: "ignore" })
+		return true
+	} catch {
+		console.warn(
+			`  ${YELLOW}Warning:${RESET} \`ntn\` not on PATH — skipping ID classification. Install ntn to catch wrong-workspace / wrong-ID-kind mistakes upfront.`,
+		)
+		return false
+	}
+}
+
+type NtnApiResult = {
+	ok: boolean
+	body?: unknown
+	/** Captured stderr from a non-404 failure (so the caller can surface it). */
+	error?: string
+	/** ntn's exit code on failure, for propagation. */
+	status?: number
+}
+
+/**
+ * 404s mean "not this kind of resource" — keep probing. Other failures (400
+ * validation errors, 401/403, network) get captured so the classifier can
+ * surface them only if every probe fails (i.e. we'd otherwise mislead the user
+ * with "not in your workspace").
+ */
+function tryNtnApi(env: string, apiPath: string): NtnApiResult {
+	const prefix =
+		env && env !== "production" ? `NOTION_KEYRING=0 ntn --env ${env}` : "ntn"
+	try {
+		const out = execSync(`${prefix} api ${apiPath}`, {
+			encoding: "utf-8",
+			stdio: "pipe",
+		})
+		try {
+			return { ok: true, body: JSON.parse(out) }
+		} catch {
+			return {
+				ok: false,
+				error: `Failed to parse successful response from ntn api ${apiPath}`,
+				status: 1,
+			}
+		}
+	} catch (err) {
+		const stderr =
+			(err as { stderr?: Buffer | string })?.stderr?.toString() ?? ""
+		if (stderr.includes("404")) {
+			return { ok: false }
+		}
+		const status = (err as { status?: number | null })?.status ?? 1
+		return { ok: false, error: stderr, status: status ?? 1 }
+	}
+}
+
+function loginCommandHint(env: string): string {
+	return env && env !== "production"
+		? `NOTION_KEYRING=0 ntn --env ${env} login`
+		: "ntn login"
+}
+
+function isDatabaseShape(body: unknown): boolean {
+	if (typeof body !== "object" || body === null) {
+		return false
+	}
+	if ("object" in body && (body as { object: unknown }).object === "database") {
+		return true
+	}
+	return (
+		"data_sources" in body &&
+		Array.isArray((body as { data_sources: unknown }).data_sources)
+	)
+}
+
+function formatDashedUuid(raw: string): string {
+	const h = raw.replace(/-/g, "")
+	if (h.length !== 32) {
+		return raw
+	}
+	return `${h.slice(0, 8)}-${h.slice(8, 12)}-${h.slice(12, 16)}-${h.slice(16, 20)}-${h.slice(20)}`
+}
+
+function bailUserInput(message: string): never {
+	console.error(`\n  ${YELLOW}Error:${RESET} ${message}\n`)
+	process.exit(EXIT_USER_ID_MISTAKE)
+}

package/scripts/utils/resolveInitArgs.ts

@@ -0,0 +1,50 @@
+/**
+ * Decide what ID the user is actually passing to the init script — the
+ * "parse the inputs" half of init's ID handling. The other half (deciding
+ * what an ID *is* — block? view? database in the wrong slot?) lives in
+ * `classifyId.ts`.
+ *
+ * Kept out of `init.ts` so the CLI/env precedence rules are unit-testable
+ * without spawning a tsx subprocess.
+ */
+
+export type InitArgsInput = {
+	/** Value of --collection, if explicitly passed. */
+	collection?: string
+	/** Value of --block or a positional Notion ID, if passed. */
+	block?: string
+	/** `process.env.BLOCK_ID` — last-resort source for the block ID. */
+	envBlockId?: string
+	/** `process.env.ENV` — populates `.notion/target.json#env`. */
+	envName?: string
+}
+
+export type InitArgsResolution = {
+	/** Block ID (from --block, positional, or BLOCK_ID env). */
+	blockId: string | undefined
+	/**
+	 * Explicit --collection value. When set, classification is skipped — we
+	 * already know the database. When undefined, we'll classify the
+	 * block-shaped input to figure out the parent DB.
+	 */
+	databaseId: string | undefined
+	/**
+	 * The single ID to feed into `classifyPositionalId`, or `undefined` to
+	 * skip classification. Set when we have a block-shaped input AND no
+	 * explicit `--collection` (otherwise the DB is already known).
+	 */
+	idToClassify: string | undefined
+	/** Env name for `.notion/target.json#env` and env-aware ntn calls. */
+	env: string
+}
+
+export function resolveInitArgs(input: InitArgsInput): InitArgsResolution {
+	const blockId = input.block || input.envBlockId || undefined
+	const databaseId = input.collection
+	// `--collection` is the user's assertion that they already know the
+	// database; otherwise we need to probe the block-shaped input to find
+	// the parent DB.
+	const idToClassify = databaseId === undefined ? blockId : undefined
+	const env = input.envName ?? "production"
+	return { blockId, databaseId, idToClassify, env }
+}

package/sdk-version.json

@@ -1 +1 @@
-{"version":"0.0.14"}
+{"version":"0.0.16"}