create-ncblock 0.0.14 → 0.0.16

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "create-ncblock",
-	"version": "0.0.14",
+	"version": "0.0.16",
 	"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,
@@ -16,6 +16,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 +118,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 +563,19 @@ 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
+			? (await ask("Database URL/ID (enter to skip):", "skip")).trim()
+			: "skip")
+	const collectionId =
+		collectionAnswer && collectionAnswer !== "skip"
+			? collectionAnswer
+			: undefined
+
 	printSummary({
 		dest,
 		name,
@@ -507,9 +584,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 +615,55 @@ 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 })
+	step(`Seeded .notion/target.json`)
+
 	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.
+		let pulled = false
+		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 {
-				// pull manifest already printed a user-friendly message
+				// 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 {
+				// 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(".")) {

package/scripts/scaffold-assets/AGENTS.md

@@ -32,6 +32,7 @@ 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
 
@@ -44,13 +45,22 @@ Two options:
    cd custom && pnpm install && pnpm run dev:shell   # http://localhost:9875
    ```
 
-## Deployment
+## Connecting to Notion
 
-Ask the user to create a block via `/custom` and copy the deploy command. It looks like:
+`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
 ```
-ntn deploy --block <block-id> <dist-path>
-```
+
+Templates will often already have some of these set in `.notion/target.json`.
 
 ## Where to look next
 

package/sdk-version.json

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

package/templates/debug/src/index.tsx

@@ -7,6 +7,7 @@ import {
 	type NotionPage,
 	type NotionPageId,
 	pages,
+	useCurrentUser,
 	useCustomBlockContext,
 	useDataSourceDefinitions,
 	useTheme,
@@ -47,6 +48,7 @@ const metaTextClass =
 
 function App() {
 	const ctx = useCustomBlockContext()
+	const currentUser = useCurrentUser()
 	const hostThemeValue = useTheme()
 	const dataSources = useDataSourceDefinitions()
 	const [isPaused, setIsPaused] = useState(false)
@@ -78,6 +80,7 @@ function App() {
 		customBlockId: ctx?.customBlockId,
 		parent: ctx?.parent,
 		page: ctx?.page,
+		currentUser,
 		dataSources,
 	}
 
@@ -93,6 +96,9 @@ function App() {
 		["viewport", `${viewport.innerWidth} \u00d7 ${viewport.innerHeight}`],
 		["contentHeight", `${viewport.scrollHeight}px`],
 		["devicePixelRatio", String(viewport.devicePixelRatio)],
+		["currentUser.id", currentUser.id],
+		["currentUser.name", currentUser.name ?? ""],
+		["currentUser.email", currentUser.person.email],
 	]
 
 	return (
@@ -856,7 +862,7 @@ function FilterMenu({
 			</IconButton>
 			{open && (
 				<div className="absolute right-0 top-full z-10 mt-1 w-56 rounded-lg border border-(--border) bg-(--card-bg) p-2 shadow-(--toast-shadow)">
-					<div className="mb-1 px-1 text-[10px] font-semibold uppercase tracking-[0.05em] opacity-40">
+					<div className="mb-1 px-1 text-[10px] font-semibold uppercase tracking-wider opacity-40">
 						Direction
 					</div>
 					{directions.map(direction => (
@@ -875,7 +881,7 @@ function FilterMenu({
 							}}
 						/>
 					))}
-					<div className="mt-2 mb-1 px-1 text-[10px] font-semibold uppercase tracking-[0.05em] opacity-40">
+					<div className="mt-2 mb-1 px-1 text-[10px] font-semibold uppercase tracking-wider opacity-40">
 						Types
 					</div>
 					{availableTypes.length === 0 ? (