create-ncblock 0.0.1

package/README.md

@@ -0,0 +1,49 @@
+# create-ncblock
+
+> [!NOTE]
+> Nothing to see here. This is **extreme** alpha and currently only works for an unreleased product.
+
+Works with `bun create`, `npm create`, `pnpm create`, and `yarn create`.
+
+```
+bun create ncblock my-view
+```
+
+No GitHub authentication required — templates are bundled in the package.
+
+> **Pre-release.** Breaking changes may land at any time before 1.0.
+
+## Usage
+
+```
+bun create ncblock [destination] [options]
+```
+
+### Options
+
+| Flag                    | Default              | Description                                   |
+| ----------------------- | -------------------- | --------------------------------------------- |
+| `--template` / `-t`    | _(interactive)_      | Template to scaffold from.                    |
+| `--name` / `-n`        | template name        | Package name for the new project.             |
+| `--git` / `--no-git`   | _(interactive)_      | Initialize a git repo.                        |
+| `--install` / `--no-install` | _(interactive)_ | Install dependencies after scaffolding.       |
+
+The first positional argument is the destination directory. If omitted, defaults to `./<name>`.
+
+### Examples
+
+```bash
+# Interactive — pick a template, name, etc.
+bun create ncblock
+
+# Non-interactive — scaffold "empty" template into ./my-view
+bun create ncblock ./my-view --template empty --name my-view --no-git --install
+
+# Works with npm and pnpm too
+npm create ncblock ./my-view -- --template empty --no-git --no-install
+pnpm create ncblock ./my-view --template empty --no-git --no-install
+```
+
+## Requirements
+
+- Node ≥ 18

package/bin/cli.js

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+import { spawnSync } from "node:child_process"
+import { createRequire } from "node:module"
+import { dirname, resolve } from "node:path"
+
+const require = createRequire(import.meta.url)
+let tsxBin
+try {
+	const tsxPkg = require.resolve("tsx/package.json")
+	tsxBin = resolve(dirname(tsxPkg), "dist/cli.mjs")
+} catch {
+	process.stderr.write(
+		"✗ Could not locate the bundled tsx runtime. Reinstall create-ncblock.\n",
+	)
+	process.exit(1)
+}
+
+const entryPath = resolve(
+	dirname(new URL(import.meta.url).pathname),
+	"..",
+	"scripts",
+	"init.ts",
+)
+const result = spawnSync(
+	"node",
+	[tsxBin, entryPath, ...process.argv.slice(2)],
+	{
+		stdio: "inherit",
+		env: process.env,
+	},
+)
+
+process.exit(result.status ?? 1)

package/package.json

@@ -0,0 +1,25 @@
+{
+	"name": "create-ncblock",
+	"version": "0.0.1",
+	"description": "Create a Notion custom view block project.",
+	"type": "module",
+	"bin": {
+		"create-ncblock": "bin/cli.js"
+	},
+	"files": [
+		"bin",
+		"scripts",
+		"templates",
+		"sdk-version.json",
+		"README.md"
+	],
+	"engines": {
+		"node": ">=18"
+	},
+	"dependencies": {
+		"tsx": "^4.21.0"
+	},
+	"publishConfig": {
+		"access": "public"
+	}
+}

package/scripts/init.ts

@@ -0,0 +1,527 @@
+import { execSync } from "child_process"
+import { basename, dirname, resolve } from "path"
+import {
+	clearScreenDown,
+	createInterface,
+	cursorTo,
+	emitKeypressEvents,
+	moveCursor,
+} from "readline"
+import { fileURLToPath } from "url"
+import {
+	getTemplateByName,
+	getTemplates,
+	scaffoldTemplate,
+	type TemplateMetadata,
+} from "./utils/templates"
+
+function detectPM(): string {
+	const ua = process.env.npm_config_user_agent ?? ""
+	if (ua.startsWith("pnpm")) {
+		return "pnpm"
+	}
+	if (ua.startsWith("bun")) {
+		return "bun"
+	}
+	if (ua.startsWith("npm")) {
+		return "npm"
+	}
+	for (const pm of ["pnpm", "bun", "npm"]) {
+		try {
+			execSync(`${pm} --version`, { stdio: "ignore" })
+			return pm
+		} catch {}
+	}
+	return "pnpm"
+}
+
+function parseArgs(argv: string[]) {
+	const args: Record<string, string | boolean> = {}
+	const positional: string[] = []
+	let i = 2
+	while (i < argv.length) {
+		const arg = argv[i]
+		if (arg === "--template" || arg === "-t") {
+			args.template = argv[++i]
+		} else if (arg === "--name" || arg === "-n") {
+			args.name = argv[++i]
+		} else if (arg === "--git") {
+			args.git = true
+		} else if (arg === "--no-git") {
+			args.git = false
+		} else if (arg === "--install") {
+			args.install = true
+		} else if (arg === "--no-install") {
+			args.install = false
+		} else if (!arg.startsWith("-")) {
+			positional.push(arg)
+		}
+		i++
+	}
+	return { args, positional }
+}
+
+const pm = detectPM()
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const root = resolve(__dirname, "..")
+const templateBaseDir = resolve(root, "templates")
+const templates = getTemplates(templateBaseDir)
+
+const c = {
+	reset: "\x1b[0m",
+	dim: "\x1b[2m",
+	bold: "\x1b[1m",
+	green: "\x1b[32m",
+	cyan: "\x1b[36m",
+	yellow: "\x1b[33m",
+}
+
+let rl: ReturnType<typeof createInterface> | undefined
+
+function getPromptInterface() {
+	rl ??= createInterface({ input: process.stdin, output: process.stdout })
+	return rl
+}
+
+function closePromptInterface() {
+	rl?.close()
+	rl = undefined
+}
+
+function question(prompt: string): Promise<string> {
+	return new Promise(res => {
+		getPromptInterface().question(prompt, res)
+	})
+}
+
+function truncateText(value: string, maxLength: number): string {
+	if (maxLength <= 0) {
+		return ""
+	}
+	if (value.length <= maxLength) {
+		return value
+	}
+	if (maxLength === 1) {
+		return "…"
+	}
+	return `${value.slice(0, maxLength - 1)}…`
+}
+
+function wrapText(value: string, maxWidth: number): string[] {
+	if (maxWidth <= 0) {
+		return [value]
+	}
+
+	const words = value.trim().split(/\s+/).filter(Boolean)
+	if (words.length === 0) {
+		return [""]
+	}
+
+	const lines: string[] = []
+	let currentLine = ""
+
+	for (const word of words) {
+		if (word.length > maxWidth) {
+			if (currentLine) {
+				lines.push(currentLine)
+				currentLine = ""
+			}
+			let remaining = word
+			while (remaining.length > maxWidth) {
+				lines.push(remaining.slice(0, maxWidth - 1) + "…")
+				remaining = remaining.slice(maxWidth - 1)
+			}
+			currentLine = remaining
+			continue
+		}
+
+		const nextLine = currentLine ? `${currentLine} ${word}` : word
+		if (nextLine.length <= maxWidth) {
+			currentLine = nextLine
+			continue
+		}
+
+		lines.push(currentLine)
+		currentLine = word
+	}
+
+	if (currentLine) {
+		lines.push(currentLine)
+	}
+
+	return lines
+}
+
+function validateProjectName(value: string): string | undefined {
+	if (value.trim().length === 0) {
+		return "Project name cannot be empty."
+	}
+	if (!/^(?:@[a-z0-9-~][a-z0-9-._~]*\/)?[a-z0-9-~][a-z0-9-._~]*$/.test(value)) {
+		return "Use a valid package name: lowercase, no spaces."
+	}
+	return undefined
+}
+
+function validateLocation(value: string): string | undefined {
+	return value.trim().length > 0 ? undefined : "Location cannot be empty."
+}
+
+async function ask(
+	label: string,
+	fallback: string,
+	override?: string,
+	validate?: (value: string) => string | undefined,
+): Promise<string> {
+	if (override !== undefined) {
+		return override
+	}
+	while (true) {
+		const answer = (
+			await question(
+				`  ${c.cyan}${label}${c.reset} ${c.dim}(${fallback})${c.reset} `,
+			)
+		).trim()
+		const value = answer || fallback
+		const error = validate?.(value)
+		if (!error) {
+			return value
+		}
+		console.log(`  ${c.yellow}${error}${c.reset}`)
+	}
+}
+
+async function confirm(
+	label: string,
+	override?: boolean,
+	defaultYes = true,
+): Promise<boolean> {
+	if (override !== undefined) {
+		return override
+	}
+	while (true) {
+		const hint = defaultYes
+			? `${c.dim}(Y/n)${c.reset}`
+			: `${c.dim}(y/N)${c.reset}`
+		const answer = (await question(`  ${c.cyan}${label}${c.reset} ${hint} `))
+			.trim()
+			.toLowerCase()
+		if (!answer) {
+			return defaultYes
+		}
+		if (answer === "y" || answer === "yes") {
+			return true
+		}
+		if (answer === "n" || answer === "no") {
+			return false
+		}
+		console.log(`  ${c.yellow}Please enter y or n.${c.reset}`)
+	}
+}
+
+const step = (msg: string) => console.log(`\n  ${c.green}✓${c.reset} ${msg}`)
+
+function formatTemplateBadges(template: TemplateMetadata): string {
+	return template.recommended ? "recommended" : ""
+}
+
+function formatTemplateLabel(template: TemplateMetadata): string {
+	const badges = formatTemplateBadges(template)
+	return `${template.title}${badges ? ` · ${badges}` : ""}`
+}
+
+function printTemplateCatalog() {
+	console.log(`  ${c.bold}Available templates${c.reset}`)
+	for (const template of templates) {
+		console.log(
+			`  ${c.cyan}${template.name}${c.reset} ${c.dim}(${formatTemplateLabel(template)})${c.reset}`,
+		)
+		console.log(`      ${template.description}`)
+	}
+	console.log("")
+}
+
+function printTemplateError(templateName: string) {
+	console.error(`\n  Template "${templateName}" not found.`)
+	console.error(`  Available templates:\n`)
+	for (const template of templates) {
+		console.error(`  - ${template.name} (${formatTemplateLabel(template)})`)
+		console.error(`    ${template.description}`)
+	}
+}
+
+function formatShellPath(path: string): string {
+	if (!/[\s"'`$\\]/.test(path)) {
+		return path
+	}
+	return `"${path.replace(/["\\$`]/g, "\\$&")}"`
+}
+
+function formatTemplatePickerLines(
+	index: number,
+	template: TemplateMetadata,
+	selected: boolean,
+): string[] {
+	const cursor = selected ? `${c.green}>${c.reset}` : " "
+	const number = `${index + 1}.`
+	const name = selected ? `${c.bold}${template.name}${c.reset}` : template.name
+	const badge = template.recommended ? ` ${c.dim}[recommended]${c.reset}` : ""
+	const columns = process.stdout.columns ?? 80
+	const descriptionPrefix = "       "
+	const descriptionWidth = Math.max(20, columns - descriptionPrefix.length - 2)
+	const wrappedDescription = wrapText(template.description, descriptionWidth)
+
+	return [
+		`  ${cursor} ${number} ${name}${badge}`,
+		...wrappedDescription.map(
+			line => `${descriptionPrefix}${c.dim}${line}${c.reset}`,
+		),
+	]
+}
+
+async function selectTemplateInteractively(
+	templateList: TemplateMetadata[],
+	defaultTemplate: TemplateMetadata,
+): Promise<TemplateMetadata> {
+	closePromptInterface()
+
+	const defaultIndex = Math.max(
+		0,
+		templateList.findIndex(template => template.name === defaultTemplate.name),
+	)
+	const maxDirectJump = Math.min(templateList.length, 9)
+
+	return new Promise(resolve => {
+		let selectedIndex = defaultIndex
+		let renderedLineCount = 0
+
+		const render = () => {
+			const lines = [
+				`  ${c.bold}Choose a template${c.reset}`,
+				`  ${c.dim}Use up/down (or j/k), Enter to select${maxDirectJump > 0 ? `, 1-${maxDirectJump} to jump` : ""}.${c.reset}`,
+				"",
+				...templateList.flatMap((template, index) =>
+					formatTemplatePickerLines(index, template, index === selectedIndex),
+				),
+				"",
+			]
+
+			if (renderedLineCount > 0) {
+				moveCursor(process.stdout, 0, -renderedLineCount)
+				cursorTo(process.stdout, 0)
+				clearScreenDown(process.stdout)
+			}
+
+			process.stdout.write(lines.join("\n") + "\n")
+			renderedLineCount = lines.length
+		}
+
+		const cleanup = () => {
+			process.stdout.write(`${c.reset}\x1b[?25h`)
+			if (renderedLineCount > 0) {
+				moveCursor(process.stdout, 0, -renderedLineCount)
+				cursorTo(process.stdout, 0)
+				clearScreenDown(process.stdout)
+			}
+			process.stdin.off("keypress", handleKeypress)
+			if (process.stdin.isTTY) {
+				process.stdin.setRawMode(false)
+			}
+			process.stdin.pause()
+		}
+
+		const handleKeypress = (
+			input: string,
+			key: { ctrl?: boolean; name?: string },
+		) => {
+			if (key.ctrl && key.name === "c") {
+				cleanup()
+				process.stdout.write("\n")
+				process.exit(1)
+			}
+
+			if (key.name === "up" || input === "k") {
+				selectedIndex =
+					(selectedIndex - 1 + templateList.length) % templateList.length
+				render()
+				return
+			}
+
+			if (key.name === "down" || input === "j") {
+				selectedIndex = (selectedIndex + 1) % templateList.length
+				render()
+				return
+			}
+
+			if (input && /^[1-9]$/.test(input)) {
+				const jumpIndex = Number(input) - 1
+				if (jumpIndex < templateList.length) {
+					selectedIndex = jumpIndex
+					render()
+				}
+				return
+			}
+
+			if (key.name === "return") {
+				const selectedTemplate = templateList[selectedIndex]
+				cleanup()
+				resolve(selectedTemplate)
+			}
+		}
+
+		emitKeypressEvents(process.stdin)
+		process.stdout.write("\x1b[?25l")
+		if (process.stdin.isTTY) {
+			process.stdin.setRawMode(true)
+		}
+		process.stdin.resume()
+		process.stdin.on("keypress", handleKeypress)
+		render()
+	})
+}
+
+async function selectTemplate(
+	defaultTemplate: TemplateMetadata,
+	override?: string,
+): Promise<TemplateMetadata> {
+	if (override !== undefined) {
+		const selectedTemplate = getTemplateByName(templateBaseDir, override)
+		if (!selectedTemplate) {
+			printTemplateError(override)
+			process.exit(1)
+		}
+		return selectedTemplate
+	}
+
+	if (!process.stdin.isTTY || !process.stdout.isTTY) {
+		printTemplateCatalog()
+		const templateName = await ask(
+			"Template:",
+			defaultTemplate.name,
+			undefined,
+			value =>
+				getTemplateByName(templateBaseDir, value)
+					? undefined
+					: `Choose one of: ${templates.map(template => template.name).join(", ")}`,
+		)
+		return getTemplateByName(templateBaseDir, templateName) ?? defaultTemplate
+	}
+
+	return selectTemplateInteractively(templates, defaultTemplate)
+}
+
+function printSummary(args: {
+	dest: string
+	name: string
+	template: TemplateMetadata
+	initGit: boolean
+	installDeps: boolean
+}) {
+	const { dest, name, template, initGit, installDeps } = args
+	console.log(`\n  ${c.bold}Summary${c.reset}`)
+	console.log(`  ${c.dim}Location:${c.reset} ${dest}`)
+	console.log(`  ${c.dim}Project name:${c.reset} ${name}`)
+	console.log(
+		`  ${c.dim}Template:${c.reset} ${template.name} ${c.dim}(${template.title})${c.reset}`,
+	)
+	console.log(`  ${c.dim}Git:${c.reset} ${initGit ? "yes" : "no"}`)
+	console.log(`  ${c.dim}Install:${c.reset} ${installDeps ? "yes" : "no"}`)
+}
+
+async function main() {
+	const { args, positional } = parseArgs(process.argv)
+	if (templates.length === 0) {
+		throw new Error("No templates found in templates/")
+	}
+	const defaultTemplate =
+		templates.find(template => template.recommended) ?? templates[0]
+
+	console.log(`\n${c.bold}  Create a new custom view${c.reset}\n`)
+
+	const selectedTemplate = await selectTemplate(
+		defaultTemplate,
+		args.template as string | undefined,
+	)
+	const name = await ask(
+		"Project name:",
+		selectedTemplate.name,
+		args.name as string | undefined,
+		validateProjectName,
+	)
+	const dir = await ask(
+		"Location:",
+		positional[0] || `./${name}`,
+		positional[0],
+		validateLocation,
+	)
+	const dest = resolve(dir)
+	const templateDir = resolve(templateBaseDir, selectedTemplate.name)
+
+	step(
+		`Using template ${c.bold}${selectedTemplate.name}${c.reset} ${c.dim}(${selectedTemplate.title})${c.reset}`,
+	)
+	console.log(`    ${selectedTemplate.description}`)
+
+	const initGit = await confirm(
+		"Initialize git repo?",
+		args.git as boolean | undefined,
+	)
+	const installDeps = await confirm(
+		"Install dependencies?",
+		args.install as boolean | undefined,
+	)
+
+	printSummary({
+		dest,
+		name,
+		template: selectedTemplate,
+		initGit,
+		installDeps,
+	})
+
+	scaffoldTemplate({ root, templateDir, dest, name })
+
+	step(`Scaffolded project in ${c.bold}${dest}${c.reset}`)
+
+	if (initGit) {
+		execSync("git init", { cwd: dest, stdio: "ignore" })
+		execSync("git add -A", { cwd: dest, stdio: "ignore" })
+		execSync('git commit -m "Initial commit"', { cwd: dest, stdio: "ignore" })
+		step("Initialized git repo")
+	}
+
+	if (installDeps) {
+		console.log("")
+		const installArgs = pm === "pnpm" ? "install --ignore-workspace" : "install"
+		execSync(`${pm} ${installArgs}`, { cwd: dest, stdio: "inherit" })
+		step("Installed dependencies")
+	}
+
+	const blockId = 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
+
+	console.log(`\n${c.bold}  Ready!${c.reset} Next steps:\n`)
+	if (dest !== resolve(".")) {
+		console.log(`  cd ${formatShellPath(dest)}`)
+	}
+	if (!installDeps) {
+		console.log(`  ${pm} install`)
+	}
+	console.log(`  ${pm} run build`)
+	if (deployCommand) {
+		console.log(`  ${deployCommand}\n`)
+	} else {
+		console.log(
+			`\n  Then, go back to the instructions in Notion and paste the ${c.bold}ntn deploy${c.reset} command.\n`,
+		)
+	}
+
+	closePromptInterface()
+}
+
+main()

package/scripts/scaffold-assets/AGENTS.md

@@ -0,0 +1,65 @@
+# {{name}}
+
+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`.
+
+## Talking to the host
+
+- Always use the React hooks from `ncblock`. Never call `window.parent.postMessage` directly — the SDK owns the protocol.
+- Render app code inside `<NotionCustomBlock>` so the handshake completes before hooks like `useTheme` or `useCustomBlockContext` run.
+
+Hooks at a glance:
+
+- `useCustomBlockContext()` — `{ customBlockId, parent, page }`.
+- `useTheme()` — `"light" | "dark"`.
+- `useDataSource(key, initialLimit?)` — `{ items, isLoading, hasMore, fetchMore, error }`.
+- `useDataSourceDefinitions()` — resolved data-source definitions (for debug/schema-driven UIs).
+- `pages.create(input)` — creates a page; pass `parent: { type: "data_source_key", key }` to target the block's wired data source.
+
+`<NotionCustomBlock>` runs `useCustomBlockAutoResize` for you by default — no extra wiring needed. Pass `autoResize={false}` for full-bleed views. Full signatures live in `node_modules/ncblock/docs/*.md` and the `.d.ts` files.
+
+## Sizing
+
+- The host owns width and height — no hard-coded widths. Layouts must reflow from a phone column to a desktop block.
+- `100vh` ≠ a screen inside an iframe. Use intrinsic sizing with `min-height`.
+- Use container queries (`@container`) — iframe width, not device width, is the real constraint.
+
+## Forbidden APIs
+
+- No top-level navigation, `window.open`, or auth redirects.
+- No network requests. All data comes through host data sources.
+
+## Conventions
+
+- 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.
+
+## Previewing during development
+
+Two options:
+
+1. **Live Notion host** — ask the user to create a block via `/custom` and paste the Vite dev URL (e.g. `http://localhost:5173`) into the block's URL field.
+2. **Mock host** — run the dev shell in another tab:
+   ```bash
+   git clone https://github.com/makenotion/custom
+   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.
+- `node_modules/ncblock/docs/lifecycle.md` — `<NotionCustomBlock>`, init, sizing, auto-resize.
+- `node_modules/ncblock/docs/context.md` — `useCustomBlockContext`, `useTheme`.
+- `node_modules/ncblock/docs/data-sources.md` — `useDataSource`, row/property/date types, worked example.
+- `node_modules/ncblock/docs/pages.md` — `pages.create / get / update / delete`.
+- `node_modules/ncblock/docs/users.md` — `users.list / get`, `NotionUser`.
+- `node_modules/ncblock/docs/manifest.md` — `custom_blocks.json` + Vite plugin.
+- `node_modules/ncblock/dist/*.d.ts` — typed surface; hover in your editor.
+- https://github.com/makenotion/custom — source and examples.