create-ncblock 0.0.16 → 0.0.17

package/package.json

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

package/scripts/init.ts

@@ -9,6 +9,7 @@ import {
 	moveCursor,
 } from "readline"
 import { fileURLToPath } from "url"
+import { resolveInitArgs } from "./utils/resolveInitArgs"
 import {
 	getTemplateByName,
 	getTemplates,
@@ -563,18 +564,30 @@ 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
+	// 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()
-			: "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,
+		installDeps,
+	})
+	const { blockId, collectionId } = resolved
 
 	printSummary({
 		dest,
@@ -615,16 +628,13 @@ 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`)
 
+	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
@@ -640,7 +650,6 @@ async function main() {
 		// 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 {
@@ -674,13 +683,30 @@ 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.
@@ -32,7 +40,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 +52,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/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.14"}
+{"version":"0.0.15"}