create-ncblock 0.0.17 → 0.0.18

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "create-ncblock",
-	"version": "0.0.17",
+	"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,11 @@ 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,
@@ -19,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
@@ -58,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(
@@ -65,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}`,
 		)
@@ -564,11 +574,8 @@ async function main() {
 		args.install as boolean | undefined,
 	)
 
-	// Ask for the database URL/ID upfront — alongside the other prompts.
-	// Precedence: --collection > --block/positional > prompt. A positional
-	// Notion ID is almost always a block inside a collection_view (or the
-	// view block itself); `manifest pull`'s resolveId() handles both cases,
-	// so we can feed the block ID straight through without re-prompting.
+	// 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
@@ -585,9 +592,14 @@ async function main() {
 		block: blockIdArg,
 		envBlockId: process.env.BLOCK_ID,
 		envName: process.env.ENV,
-		installDeps,
 	})
-	const { blockId, collectionId } = resolved
+	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,
@@ -628,17 +640,19 @@ async function main() {
 		step("Initialized git repo")
 	}
 
-	// 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: 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 pulled = false
+	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("")
@@ -646,26 +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.
-		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
 			}
@@ -690,20 +694,11 @@ async function main() {
 		)
 	}
 
-	// If install ran but no data source was wired (no collectionId, or a
-	// pull/connect failure), surface the manual CLI commands explicitly.
-	// Agents read this scrollback — being concrete here keeps them from
-	// reinventing the bridge or hardcoding IDs.
-	if (installDeps && !pulled) {
+	if (installDeps && !connected) {
 		console.log(
 			`\n  ${c.yellow}No data source connected yet.${c.reset} To wire one up:`,
 		)
-		console.log(`    npx ncblock manifest pull <database-url-or-id>`)
-		if (!blockId) {
-			console.log(`    npx ncblock connect --block <block-id-or-url>`)
-		} else {
-			console.log(`    npx ncblock connect`)
-		}
+		console.log(`    npx ncblock connect <database-url-or-id>`)
 	}
 	console.log("")
 

package/scripts/scaffold-assets/AGENTS.md

@@ -4,12 +4,14 @@ A **Notion custom view** — a sandboxed `<iframe>` rendered inside a Notion blo
 
 ## 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. Use the `npx ncblock` cli to connect the database and the project. Discover available commands with:
+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 --help
+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.

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

@@ -1,9 +1,11 @@
 /**
- * Pure resolution of init.ts's data-source / block / env wiring decisions.
+ * 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`.
  *
- * Pulled out of init.ts so the precedence rules — especially "positional/--block
- * Notion ID should also drive `manifest pull` when no --collection is given" —
- * are unit-testable without spawning a tsx subprocess.
+ * Kept out of `init.ts` so the CLI/env precedence rules are unit-testable
+ * without spawning a tsx subprocess.
  */
 
 export type InitArgsInput = {
@@ -11,49 +13,38 @@ export type InitArgsInput = {
 	collection?: string
 	/** Value of --block or a positional Notion ID, if passed. */
 	block?: string
-	/** `process.env.BLOCK_ID` — used as a last resort for block resolution. */
+	/** `process.env.BLOCK_ID` — last-resort source for the block ID. */
 	envBlockId?: string
 	/** `process.env.ENV` — populates `.notion/target.json#env`. */
 	envName?: string
-	/** Whether `init` will run install + ncblock pull/connect (--install / --no-install). */
-	installDeps: boolean
 }
 
 export type InitArgsResolution = {
+	/** Block ID (from --block, positional, or BLOCK_ID env). */
 	blockId: string | undefined
-	collectionId: 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
-	/** Will init invoke `ncblock manifest pull`? */
-	willPullManifest: boolean
-	/** Will init invoke `ncblock connect`? (only when pull will also run) */
-	willConnect: boolean
 }
 
-/**
- * Decide what init will actually do, given the args. Precedence:
- *
- * 1. `--collection` is the explicit manifest-pull target (highest priority).
- * 2. Otherwise, a positional/`--block` Notion ID doubles as the pull target —
- *    `manifest pull`'s resolveId() handles "block inside collection_view" and
- *    walks to the parent data source. This is the path users hit with
- *    `bun create ncblock <block-id>`.
- * 3. When neither is set, no pull happens.
- *
- * `manifest pull` and `connect` only run when install ran (otherwise the
- * ncblock CLI isn't on disk to call).
- */
 export function resolveInitArgs(input: InitArgsInput): InitArgsResolution {
 	const blockId = input.block || input.envBlockId || undefined
-	// A block ID doubles as the pull target: `manifest pull` accepts a block
-	// (resolveId walks block → parent → data source), and that's the path
-	// users hit with `bun create ncblock <block-id>`. Derived from `blockId`
-	// rather than `input.block` directly so envBlockId flows through too —
-	// no point treating `--block` and `BLOCK_ID=` differently.
-	const collectionId = input.collection ?? blockId
+	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"
-
-	const willPullManifest = input.installDeps && collectionId !== undefined
-	const willConnect = willPullManifest && blockId !== undefined
-
-	return { blockId, collectionId, env, willPullManifest, willConnect }
+	return { blockId, databaseId, idToClassify, env }
 }

package/sdk-version.json

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