create-ncblock 0.0.15 → 0.0.17

package/package.json

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

package/scripts/init.ts

@@ -1,5 +1,5 @@
-import { execSync } from "child_process"
-import { existsSync, readdirSync } from "fs"
+import { execSync, spawnSync } from "child_process"
+import { existsSync, mkdirSync, readdirSync, writeFileSync } from "fs"
 import { basename, dirname, resolve } from "path"
 import {
 	clearScreenDown,
@@ -9,6 +9,7 @@ import {
 	moveCursor,
 } from "readline"
 import { fileURLToPath } from "url"
+import { resolveInitArgs } from "./utils/resolveInitArgs"
 import {
 	getTemplateByName,
 	getTemplates,
@@ -16,6 +17,63 @@ import {
 	type TemplateMetadata,
 } from "./utils/templates"
 
+/**
+ * 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.
+ */
+type InitialTarget = {
+	env: string
+	block_id: string[]
+	data_sources: Record<
+		string,
+		{ data_source_id: string; property_ids_by_key: Record<string, string> }
+	>
+}
+
+function writeInitialTarget(
+	dest: string,
+	args: { env?: string; blockId?: string },
+): void {
+	const target: InitialTarget = {
+		env: args.env ?? "production",
+		block_id: args.blockId ? [args.blockId] : [],
+		data_sources: {},
+	}
+	mkdirSync(resolve(dest, ".notion"), { recursive: true })
+	writeFileSync(
+		resolve(dest, ".notion/target.json"),
+		JSON.stringify(target, null, "\t") + "\n",
+	)
+}
+
+/**
+ * Run the locally-installed `ncblock` CLI from a scaffolded project.
+ *
+ * We bypass `npx` / `pnpm exec` / `bunx` deliberately: those wrappers can
+ * spawn the binary in a way that lets `execSync` return before the child's
+ * stdout fully drains, which makes pull-manifest's output land out of order
+ * (e.g. after init has already exited). Invoking the .js entrypoint via
+ * `node` is synchronous and deterministic.
+ *
+ * Env is sourced from target.json (written by writeInitialTarget before
+ * any ncblock call) — no need to thread ENV through the spawn.
+ */
+function runNcblock(dest: string, args: string[]): void {
+	const result = spawnSync(
+		process.execPath,
+		[resolve(dest, "node_modules/ncblock/bin/cli/cli.js"), ...args],
+		{ cwd: dest, stdio: "inherit" },
+	)
+	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}`,
+		)
+	}
+}
+
 function detectPM(): string {
 	const ua = process.env.npm_config_user_agent ?? ""
 	if (ua.startsWith("pnpm")) {
@@ -61,9 +119,16 @@ function parseArgs(argv: string[]) {
 			args.force = true
 		} else if (arg === "--collection") {
 			args.collection = argv[++i]
+		} else if (arg === "--block") {
+			args.block = argv[++i]
+		} else if (arg === "--local-sdk") {
+			args.localSdk = true
 		} else if (!arg.startsWith("-")) {
+			// Positional Notion ID has always been captured as a block ID — the
+			// variable name (and the deploy hint that uses it) reflect that.
+			// Prefer --block when set; otherwise positional is the block.
 			if (NOTION_ID_RE.test(arg)) {
-				args.blockId = arg
+				args.block ??= arg
 			} else {
 				positional.push(arg)
 			}
@@ -499,6 +564,31 @@ 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.
+	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()
+			: 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,
+		installDeps,
+	})
+	const { blockId, collectionId } = resolved
+
 	printSummary({
 		dest,
 		name,
@@ -507,9 +597,29 @@ async function main() {
 		installDeps,
 	})
 
-	scaffoldTemplate({ root, templateDir, dest, name, overwrite: destNonEmpty })
+	const useLocalSdk = args.localSdk === true
+	// Dynamic import: `pack-local-sdk` depends on `build-sdk`, which is not
+	// bundled into the published `create-ncblock` package. Resolving it
+	// statically here would crash `bun create ncblock`.
+	const sdkDep = useLocalSdk
+		? (await import("./utils/pack-local-sdk")).packLocalSdk(dest)
+		: undefined
+
+	scaffoldTemplate({
+		root,
+		templateDir,
+		dest,
+		name,
+		overwrite: destNonEmpty,
+		sdkDep,
+	})
 
 	step(`Scaffolded project in ${c.bold}${dest}${c.reset}`)
+	if (useLocalSdk) {
+		step(
+			`Using locally-packed SDK ${c.dim}(file:${sdkDep?.replace("file:./", "")})${c.reset}`,
+		)
+	}
 
 	if (initGit) {
 		execSync("git init", { cwd: dest, stdio: "ignore" })
@@ -518,45 +628,51 @@ 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`)
+
+	let pulled = 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.
+		closePromptInterface()
+
 		console.log("")
 		const installArgs = pm === "pnpm" ? "install --ignore-workspace" : "install"
 		execSync(`${pm} ${installArgs}`, { cwd: dest, stdio: "inherit" })
 		step("Installed dependencies")
 
-		// Resolve a block/database ID to populate custom_blocks.json. Prefer
-		// explicit flags/env over prompting — if the user already gave us an
-		// ID, `ncblock pull manifest` can resolve it (block or database) on
-		// its own, no prompt needed.
-		const explicitId =
-			(args.collection as string | undefined) ??
-			(args.blockId as string | undefined) ??
-			process.env.BLOCK_ID
-		const blockOrCollectionId =
-			explicitId ??
-			(await ask("Database URL/ID (enter to skip):", "skip")).trim()
-		if (blockOrCollectionId && blockOrCollectionId !== "skip") {
+		// `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) {
 			console.log("")
 			try {
-				execSync(`npx ncblock pull manifest ${blockOrCollectionId}`, {
-					cwd: dest,
-					stdio: "inherit",
-				})
+				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)")
 			} catch {
-				// pull manifest already printed a user-friendly message
+				// connect already printed a user-friendly message
 			}
 		}
 	}
 
-	const blockId = (args.blockId as string | undefined) || process.env.BLOCK_ID
-	const envName = process.env.ENV
-	const deployCommand =
-		blockId && envName
-			? `NOTION_KEYRING=0 ntn --env ${envName} custom deploy --block ${blockId} dist/`
-			: blockId
-				? `ntn custom deploy --block ${blockId} dist/`
-				: undefined
+	const deployCommand = blockId ? `npx ncblock deploy dist/` : undefined
 
 	console.log(`\n${c.bold}  Ready!${c.reset} Next steps:\n`)
 	if (dest !== resolve(".")) {
@@ -567,12 +683,29 @@ 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 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) {
+		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("")
 
 	closePromptInterface()
 }

package/scripts/scaffold-assets/AGENTS.md

@@ -2,6 +2,14 @@
 
 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. Use the `npx ncblock` cli to connect the database and the project. Discover available commands with:
+
+```bash
+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.
@@ -44,14 +52,6 @@ Two options:
    cd custom && pnpm install && pnpm run dev:shell   # http://localhost:9875
    ```
 
-## Deployment
-
-Ask the user to create a block via `/custom` and copy the deploy command. It looks like:
-
-```
-ntn deploy --block <block-id> <dist-path>
-```
-
 ## Where to look next
 
 - `node_modules/ncblock/README.md` — landing page with a TOC into the per-category docs below.

package/scripts/utils/resolveInitArgs.ts

@@ -0,0 +1,59 @@
+/**
+ * Pure resolution of init.ts's data-source / block / env wiring decisions.
+ *
+ * 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.
+ */
+
+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` — used as a last resort for block resolution. */
+	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 = {
+	blockId: string | undefined
+	collectionId: string | undefined
+	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 env = input.envName ?? "production"
+
+	const willPullManifest = input.installDeps && collectionId !== undefined
+	const willConnect = willPullManifest && blockId !== undefined
+
+	return { blockId, collectionId, env, willPullManifest, willConnect }
+}

package/sdk-version.json

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