@notionhq/custom-blocks 0.0.79 → 0.1.1

package/README.md

@@ -47,7 +47,9 @@ API surface, one page per category. Import framework-neutral APIs from `@notionh
 - [`docs/pages.md`](./docs/pages.md) — `pages.create / get / update / delete`, parent variants (including the recommended `data_source_key`), property input shapes.
 - [`docs/users.md`](./docs/users.md) — `users.list / get`, the `NotionUser` shape, paging.
 - [`docs/errors.md`](./docs/errors.md) — request results, error format, error codes, retries, and initialization failures.
-- [`docs/manifest.md`](./docs/manifest.md) — `custom_blocks.json`, the Vite plugin, manifest types.
+- [`docs/vite-plugin.md`](./docs/vite-plugin.md) — the `notionCustomBlock()` Vite plugin and `custom_blocks.json`, the block's local-preview manifest.
+
+Declare the block source and data-source schema in the worker file with `worker.customBlock(...)`, then build and deploy it with `ntn workers deploy`. The worker definition is the source of truth; the iframe frontend uses semantic keys from that definition with APIs such as `useDataSource`. For local previews, the Vite plugin serves the block's `custom_blocks.json` — see [`docs/vite-plugin.md`](./docs/vite-plugin.md).
 
 ## Forbidden APIs
 

package/dist/bridge/dataSources/errors.d.ts

@@ -1,5 +1,5 @@
 import * as v from "valibot";
-import type { CustomBlockErrorInfo } from "../errors";
+import type { CustomBlockErrorInfo } from "../errors.js";
 export declare const customBlockDataSourceResolutionErrorCodeSchema: v.StringSchema<undefined>;
 export type CustomBlockDataSourceResolutionErrorCode = "unknown_data_source_key" | "unmapped_data_source" | (string & {});
 export type CustomBlockDataSourceResolutionErrorInfo = CustomBlockErrorInfo<CustomBlockDataSourceResolutionErrorCode>;

package/dist/bridge/dataSources/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../../../home/runner/work/custom-blocks/custom-blocks/sdk/src/bridge/dataSources/errors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,SAAS,CAAA;AAC5B,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,WAAW,CAAA;AAIrD,eAAO,MAAM,8CAA8C,2BAAa,CAAA;AAExE,MAAM,MAAM,wCAAwC,GACjD,yBAAyB,GACzB,sBAAsB,GACtB,CAAC,MAAM,GAAG,EAAE,CAAC,CAAA;AAEhB,MAAM,MAAM,wCAAwC,GACnD,oBAAoB,CAAC,wCAAwC,CAAC,CAAA"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../../../home/runner/work/custom-blocks/custom-blocks/sdk/src/bridge/dataSources/errors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,SAAS,CAAA;AAC5B,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAA;AAIxD,eAAO,MAAM,8CAA8C,2BAAa,CAAA;AAExE,MAAM,MAAM,wCAAwC,GACjD,yBAAyB,GACzB,sBAAsB,GACtB,CAAC,MAAM,GAAG,EAAE,CAAC,CAAA;AAEhB,MAAM,MAAM,wCAAwC,GACnD,oBAAoB,CAAC,wCAAwC,CAAC,CAAA"}

package/dist/bridge/dataSources/resolveProperty.d.ts

@@ -1,5 +1,5 @@
 import * as v from "valibot";
-import type { CustomBlockErrorInfo } from "../errors";
+import type { CustomBlockErrorInfo } from "../errors.js";
 import type { NotionPagePropertyInputMap, NotionPagePropertyWriteMap } from "../pages/page.js";
 import type { NotionDataSource } from "./dataSource.js";
 export declare const customBlockPropertyErrorCodeSchema: v.StringSchema<undefined>;

package/dist/bridge/dataSources/resolveProperty.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resolveProperty.d.ts","sourceRoot":"","sources":["../../../../../home/runner/work/custom-blocks/custom-blocks/sdk/src/bridge/dataSources/resolveProperty.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,SAAS,CAAA;AAC5B,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,WAAW,CAAA;AACrD,OAAO,KAAK,EACX,0BAA0B,EAC1B,0BAA0B,EAC1B,MAAM,kBAAkB,CAAA;AAEzB,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAA;AAIvD,eAAO,MAAM,kCAAkC,2BAAa,CAAA;AAE5D,MAAM,MAAM,4BAA4B,GACrC,mBAAmB,GACnB,sBAAsB,GACtB,oBAAoB,GACpB,wBAAwB,GACxB,CAAC,MAAM,GAAG,EAAE,CAAC,CAAA;AAEhB,MAAM,MAAM,4BAA4B,GACvC,oBAAoB,CAAC,4BAA4B,CAAC,CAAA;AAEnD,MAAM,MAAM,gCAAgC,GACzC;IAAE,MAAM,EAAE,SAAS,CAAC;IAAC,UAAU,EAAE,0BAA0B,CAAA;CAAE,GAC7D;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,4BAA4B,CAAA;CAAE,CAAA;AAS3D;;;;;;GAMG;AACH,wBAAgB,oCAAoC,CAAC,IAAI,EAAE;IAC1D,UAAU,EAAE,gBAAgB,GAAG,SAAS,CAAA;IACxC,UAAU,EAAE,0BAA0B,CAAA;IACtC,aAAa,EAAE,MAAM,CAAA;CACrB,GAAG,gCAAgC,CAwDnC;AAED;;;GAGG;AACH,wBAAgB,sCAAsC,CAAC,IAAI,EAAE;IAC5D,UAAU,EAAE,gBAAgB,GAAG,SAAS,CAAA;IACxC,UAAU,EAAE,MAAM,CAAA;IAClB,aAAa,EAAE,MAAM,CAAA;CACrB,GACE;IAAE,MAAM,EAAE,SAAS,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,GACzC;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,4BAA4B,CAAA;CAAE,CAsB1D"}
+{"version":3,"file":"resolveProperty.d.ts","sourceRoot":"","sources":["../../../../../home/runner/work/custom-blocks/custom-blocks/sdk/src/bridge/dataSources/resolveProperty.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,SAAS,CAAA;AAC5B,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAA;AACxD,OAAO,KAAK,EACX,0BAA0B,EAC1B,0BAA0B,EAC1B,MAAM,kBAAkB,CAAA;AAEzB,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAA;AAIvD,eAAO,MAAM,kCAAkC,2BAAa,CAAA;AAE5D,MAAM,MAAM,4BAA4B,GACrC,mBAAmB,GACnB,sBAAsB,GACtB,oBAAoB,GACpB,wBAAwB,GACxB,CAAC,MAAM,GAAG,EAAE,CAAC,CAAA;AAEhB,MAAM,MAAM,4BAA4B,GACvC,oBAAoB,CAAC,4BAA4B,CAAC,CAAA;AAEnD,MAAM,MAAM,gCAAgC,GACzC;IAAE,MAAM,EAAE,SAAS,CAAC;IAAC,UAAU,EAAE,0BAA0B,CAAA;CAAE,GAC7D;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,4BAA4B,CAAA;CAAE,CAAA;AAS3D;;;;;;GAMG;AACH,wBAAgB,oCAAoC,CAAC,IAAI,EAAE;IAC1D,UAAU,EAAE,gBAAgB,GAAG,SAAS,CAAA;IACxC,UAAU,EAAE,0BAA0B,CAAA;IACtC,aAAa,EAAE,MAAM,CAAA;CACrB,GAAG,gCAAgC,CAwDnC;AAED;;;GAGG;AACH,wBAAgB,sCAAsC,CAAC,IAAI,EAAE;IAC5D,UAAU,EAAE,gBAAgB,GAAG,SAAS,CAAA;IACxC,UAAU,EAAE,MAAM,CAAA;IAClB,aAAa,EAAE,MAAM,CAAA;CACrB,GACE;IAAE,MAAM,EAAE,SAAS,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,GACzC;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,4BAA4B,CAAA;CAAE,CAsB1D"}

package/dist/version.js

@@ -4,4 +4,4 @@
  *
  * WARNING: Generated during SDK publish. Do not edit in the published package.
  */
-export const CUSTOM_BLOCKS_SDK_VERSION = "0.0.79"
+export const CUSTOM_BLOCKS_SDK_VERSION = "0.1.1"

package/docs/data-sources.md

@@ -1,8 +1,10 @@
 # Data sources
 
-A custom block declares its **data sources** — semantic keys like `people` or `tasks` — in `custom_blocks.json`.
+A custom block declares its **data sources** — semantic keys like `people` or `tasks` — in the worker's `worker.customBlock(...)` configuration.
 
-Data source mapping - resolving keys to ids - is stored on the block itself. This can be read/written programmatically using the `ncblock` CLI (try `npx ncblock --help`) or in the Notion UI.
+The mapping from those semantic keys to concrete Notion data sources is stored on each block instance and configured in Notion.
+
+Use `ManifestDataSource`, `ManifestProperty`, and `ManifestIcon` when code needs the corresponding definition metadata types.
 
 At runtime, your code references the semantic key and the SDK handles the lookup for you. Use `useDataSource(key)` for the rows themselves (it also exposes the resolved schema), and `useManifest()` when you need the declared data-source keys and their declarations (e.g. picking a default key, or rendering a key switcher). For non-React renderers, `customBlock.getManifest()` exposes the same manifest, but row querying is currently only exposed through the React `useDataSource` hook.
 

package/docs/vite-plugin.md

@@ -0,0 +1,46 @@
+# Vite plugin
+
+The `notionCustomBlock()` plugin from `@notionhq/custom-blocks/vite` wires a block's local dev server and build output to the SDK handshake.
+
+```ts
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react";
+import { notionCustomBlock } from "@notionhq/custom-blocks/vite";
+
+export default defineConfig({
+  plugins: [react(), notionCustomBlock()],
+});
+```
+
+In dev, the plugin serves `custom_blocks.json` from the project root so HMR and the SDK handshake see the same file. On `vite build`, it emits `custom_blocks.json` into `dist/` as a separate asset alongside the bundled HTML and JS. It also forces Vite's `base` to `"./"` (and rejects any other explicit value) — custom blocks are served from a content-addressed path, so asset URLs in the built bundle must be relative.
+
+## `custom_blocks.json` and local previews
+
+`custom_blocks.json` is the block's local manifest — the data-source keys and property shapes the block expects:
+
+```json
+{
+  "version": 1,
+  "dataSources": {
+    "tasks": {
+      "name": "Tasks",
+      "description": "The collection of tasks to render",
+      "properties": {
+        "title": { "name": "Title", "type": "title" },
+        "dueDate": { "name": "Due date", "type": "date" }
+      }
+    }
+  }
+}
+```
+
+For a worker-backed block, the `worker.customBlock(...)` declaration in the worker's `src/index.ts` is the source of truth at deploy time. But local previews (pasting the Vite dev URL into a live Notion block, or the dev shell) don't read the worker declaration — the SDK fetches `custom_blocks.json` from the plugin and forwards it on `connect`, and the host binds data sources against those keys. Keep the file mirroring the worker's `dataSources` schema so previews see the same slots the deployed block will; leave it as `{ "version": 1, "dataSources": {} }` if the block reads no host data.
+
+If the file is missing, the SDK omits `manifest` from `connect`. If it is unreadable or invalid, the SDK sends `connect` with `status: "error"` and an `error` payload. The host returns its authoritative manifest in `init`, and the SDK uses that one even when it differs from what was sent in `connect`.
+
+## Types
+
+- `CustomBlockManifest` — the parsed shape of `custom_blocks.json`.
+- `ManifestDataSource` — a single entry in `dataSources` (name, description, properties).
+- `ManifestProperty` — a single property declaration inside a `ManifestDataSource`.
+- `ManifestIcon` — the icon variant accepted on a `ManifestDataSource`.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@notionhq/custom-blocks",
-	"version": "0.0.79",
+	"version": "0.1.1",
 	"license": "MIT",
 	"type": "module",
 	"publishConfig": {
@@ -32,7 +32,6 @@
 		}
 	},
 	"bin": {
-		"ncblock": "./bin/cli/cli.js",
 		"notion-custom-blocks": "./bin/notion-custom-blocks/cli.js"
 	},
 	"scripts": {

package/src/bridge/dataSources/errors.ts

@@ -1,5 +1,5 @@
 import * as v from "valibot"
-import type { CustomBlockErrorInfo } from "../errors"
+import type { CustomBlockErrorInfo } from "../errors.js"
 
 // The schema accepts any string code. The type lists known codes for
 // autocomplete, with an open string fallback for newer senders.

package/src/bridge/dataSources/resolveProperty.ts

@@ -1,5 +1,5 @@
 import * as v from "valibot"
-import type { CustomBlockErrorInfo } from "../errors"
+import type { CustomBlockErrorInfo } from "../errors.js"
 import type {
 	NotionPagePropertyInputMap,
 	NotionPagePropertyWriteMap,

package/bin/cli/attach.js

@@ -1,180 +0,0 @@
-import { extractId, formatUuid } from "./ids.js";
-import { ntnApi, ntnApiPatch, ntnWorkersCapabilities } from "./ntn.js";
-// ── Capability resolution ───────────────────────────────────────
-function normalizeCapabilities(raw) {
-    if (Array.isArray(raw)) {
-        return raw;
-    }
-    if (raw && typeof raw === "object") {
-        const obj = raw;
-        for (const field of ["capabilities", "results", "data"]) {
-            if (Array.isArray(obj[field])) {
-                return obj[field];
-            }
-        }
-    }
-    return [];
-}
-function capabilityKey(cap) {
-    for (const field of ["key", "name", "id"]) {
-        const value = cap[field];
-        if (typeof value === "string" && value.length > 0) {
-            return value;
-        }
-    }
-    return undefined;
-}
-function capabilityType(cap) {
-    // `ntn` reports the capability kind under `_tag`; accept `type` too in case
-    // the wire shape shifts.
-    for (const field of ["_tag", "type"]) {
-        const value = cap[field];
-        if (typeof value === "string") {
-            return value;
-        }
-    }
-    return undefined;
-}
-function isCustomBlockCapability(cap) {
-    const type = capabilityType(cap);
-    // When no type field is present we can't filter — keep it and let the
-    // count-based selection below decide.
-    if (type === undefined) {
-        return true;
-    }
-    return type === "customBlock" || type === "custom_block";
-}
-function firstString(obj, fields) {
-    for (const field of fields) {
-        const value = obj[field];
-        if (typeof value === "string" && value.length > 0) {
-            return value;
-        }
-    }
-    return undefined;
-}
-function capabilityDefinitionId(cap) {
-    const top = firstString(cap, ["definition_id", "definitionId"]);
-    if (top) {
-        return top;
-    }
-    // The real `ntn` shape nests it under `state.definitionId`.
-    const state = cap.state;
-    if (state && typeof state === "object") {
-        const nested = firstString(state, [
-            "definitionId",
-            "definition_id",
-        ]);
-        if (nested) {
-            return nested;
-        }
-    }
-    // Some shapes nest the definition under a `definition` object.
-    const definition = cap.definition;
-    if (definition && typeof definition === "object") {
-        const id = definition.id;
-        if (typeof id === "string" && id.length > 0) {
-            return id;
-        }
-    }
-    return undefined;
-}
-/**
- * Resolve a worker's custom-block capability to a `definition_id`.
- *
- * - Filters `ntn workers capabilities list` down to customBlock capabilities.
- * - With `capability` set, picks the entry with that key.
- * - With exactly one candidate, uses it.
- * - With more than one and no `capability`, errors with the available keys.
- */
-export function resolveDefinitionId(capability) {
-    const raw = ntnWorkersCapabilities();
-    const all = normalizeCapabilities(raw);
-    if (all.length === 0) {
-        console.error("Error: no worker capabilities found. Deploy the worker first with `ntn workers deploy`.\n");
-        console.error("  Raw `ntn workers capabilities list --json` output:");
-        console.error(JSON.stringify(raw, null, "\t"));
-        process.exit(1);
-    }
-    const customBlocks = all.filter(isCustomBlockCapability);
-    if (customBlocks.length === 0) {
-        console.error("Error: this worker exposes no customBlock capability to attach.\n");
-        process.exit(1);
-    }
-    let selected;
-    if (capability) {
-        const match = customBlocks.find(c => capabilityKey(c) === capability);
-        if (!match) {
-            const keys = customBlocks.map(c => capabilityKey(c) ?? "(unnamed)");
-            console.error(`Error: no customBlock capability named '${capability}'.\n`);
-            console.error(`  Available: ${keys.join(", ")}`);
-            process.exit(1);
-        }
-        selected = match;
-    }
-    else if (customBlocks.length > 1) {
-        const keys = customBlocks.map(c => capabilityKey(c) ?? "(unnamed)");
-        console.error(`Error: this worker exposes ${customBlocks.length} customBlock capabilities. Pick one with --capability <key>.\n`);
-        console.error(`  Available: ${keys.join(", ")}`);
-        process.exit(1);
-    }
-    else {
-        selected = customBlocks[0];
-    }
-    const definitionId = capabilityDefinitionId(selected);
-    if (!definitionId) {
-        console.error("Error: could not read a definition_id from the selected capability.\n");
-        console.error("  Raw capability entry:");
-        console.error(JSON.stringify(selected, null, "\t"));
-        process.exit(1);
-    }
-    return { definitionId, capabilityKey: capabilityKey(selected) };
-}
-/**
- * Body for pointing a custom block at a worker's definition. The update-block
- * endpoint requires the payload be keyed by block type — a top-level
- * `definition_id` is rejected (`should be not present`). So it nests under
- * `custom_block`, matching how `patchBlock` (datasources.ts) sets data_sources.
- */
-function definitionPatchBody(definitionId) {
-    return { custom_block: { definition_id: definitionId } };
-}
-/**
- * Point an existing custom block at a worker's customBlock definition.
- *
- * Resolves the block, verifies it's a `custom_block`, resolves the worker's
- * definition_id (erroring on ambiguity), then PATCHes the block. Returns the
- * dashed block UUID so callers (e.g. `create`) can chain.
- */
-export function attach(options) {
-    const uuid = formatUuid(extractId(options.idOrUrl));
-    if (!options.jsonOutput) {
-        console.log(`\nFetching block ${uuid}…`);
-    }
-    const block = ntnApi(`/v1/blocks/${uuid}`);
-    if (block.type !== "custom_block") {
-        console.error(`Error: block ${uuid} is type "${block.type}", not "custom_block".\n`);
-        console.error("  Pass a custom block's ID/URL, or create one with `ncblock create`.");
-        process.exit(1);
-    }
-    const { definitionId, capabilityKey: key } = resolveDefinitionId(options.capability);
-    if (!options.jsonOutput) {
-        console.log(`Attaching definition ${definitionId}${key ? ` (capability "${key}")` : ""}…`);
-    }
-    ntnApiPatch(`/v1/blocks/${uuid}`, definitionPatchBody(definitionId));
-    const emitResult = options.emitResult ?? true;
-    if (options.jsonOutput) {
-        if (emitResult) {
-            console.log(JSON.stringify({
-                action: "attach",
-                block_id: uuid,
-                definition_id: definitionId,
-                capability: key,
-            }, null, "\t"));
-        }
-    }
-    else {
-        console.log(`\n✓ Attached block ${uuid} to definition ${definitionId}\n`);
-    }
-    return uuid;
-}

package/bin/cli/cli.js

@@ -1,248 +0,0 @@
-#!/usr/bin/env node
-import { attach } from "./attach.js";
-import { create } from "./create.js";
-import { connect, getDataSources } from "./datasources.js";
-import { deploy } from "./deploy.js";
-import { pullData } from "./pullData.js";
-import { pullManifest } from "./pullManifest.js";
-const HELP = `
-ncblock — Notion Custom Block SDK CLI
-
-Usage:
-  ncblock connect <database-url-or-id> [options]
-  ncblock connect [--block <id>] [--bind <key>=<ds-id>] [options]
-  ncblock data_sources get <block-id-or-url>
-  ncblock deploy <dist-path> [--block <id>] [options]
-  ncblock pull_data <id-or-url> [--limit <n>] [--out <path>]
-  ncblock attach <block-id-or-url> [--capability <key>]
-  ncblock create [--parent <id-or-url>] [--capability <key>]
-
-Commands:
-  connect            Pull the data source schema and PATCH the block(s) in .notion/target.json
-  data_sources get   Read data source bindings from a custom block
-  deploy             Run \`ntn custom deploy\` for each block; appends --block IDs into target.json on success
-  pull_data          Resolve an ID/URL to a data source; print its schema + N rows as JSON to stdout
-  attach             Point a custom block at the worker's definition (from \`ntn workers capabilities\`)
-  create             Create a custom block (private page parent by default) and attach it
-
-Options:
-  --block <id>       Block ID/URL (repeatable; accumulates into target.json's block_id[])
-  --bind <key>=<id>  Bind a manifest key to a data source ID (repeatable)
-  --capability <key> customBlock capability key to attach (required if the worker has more than one)
-  --parent <id>      Parent ID/URL for \`create\` (a page hosts the block; omit for a new private page)
-  --limit <n>        Rows to pull for \`pull_data\` (default: 25, max: 100)
-  --env <name>       Notion env (defaults to target.json's env, or "production")
-  --key <key>        Data source key in manifest (default: "default") — for connect <id> only
-  --out <path>       Output path — manifest for connect, JSON file for pull_data
-  --manifest <path>  Path to custom_blocks.json (default: "./custom_blocks.json")
-  --dry-run          Print the intended action without performing it
-  --json             Emit machine-parseable JSON output
-  --help, -h         Show this help message
-
-Examples:
-  ncblock connect <db-url>
-  ncblock connect --block <block-id> --bind default=<db-id>
-  ncblock data_sources get <block-id>
-  ncblock deploy dist/
-  ncblock pull_data <db-url> --limit 50 --out sample.json
-  ncblock attach <block-url> --capability hello
-  ncblock create
-`;
-function parseArgs(argv) {
-    const flags = {};
-    const bindings = {};
-    const blocks = [];
-    const positional = [];
-    let i = 2;
-    while (i < argv.length) {
-        const arg = argv[i];
-        if (arg === "--key") {
-            flags.key = argv[++i];
-        }
-        else if (arg === "--out") {
-            flags.out = argv[++i];
-        }
-        else if (arg === "--dry-run") {
-            flags.dryRun = true;
-        }
-        else if (arg === "--json") {
-            flags.jsonOutput = true;
-        }
-        else if (arg === "--quiet") {
-            flags.quiet = true;
-        }
-        else if (arg === "--manifest") {
-            flags.manifest = argv[++i];
-        }
-        else if (arg === "--capability") {
-            flags.capability = argv[++i];
-        }
-        else if (arg === "--parent") {
-            flags.parent = argv[++i];
-        }
-        else if (arg === "--limit") {
-            flags.limit = argv[++i];
-        }
-        else if (arg === "--env") {
-            flags.env = argv[++i];
-        }
-        else if (arg === "--block") {
-            const value = argv[++i];
-            if (!value) {
-                console.error("Error: --block requires a value.\n");
-                console.error("Usage: --block <id-or-url>");
-                process.exit(1);
-            }
-            blocks.push(value);
-        }
-        else if (arg === "--bind") {
-            const pair = argv[++i];
-            const eq = pair?.indexOf("=");
-            if (!pair || eq === undefined || eq < 1) {
-                console.error(`Error: invalid --bind value: ${pair}\n`);
-                console.error("Expected format: --bind <key>=<data-source-id>");
-                process.exit(1);
-            }
-            bindings[pair.slice(0, eq)] = pair.slice(eq + 1);
-        }
-        else if (arg === "--help" || arg === "-h") {
-            flags.help = true;
-        }
-        else if (!arg.startsWith("-")) {
-            positional.push(arg);
-        }
-        i++;
-    }
-    return { flags, bindings, blocks, positional };
-}
-function main() {
-    const { flags, bindings, blocks, positional } = parseArgs(process.argv);
-    if (flags.help || positional.length === 0) {
-        console.log(HELP);
-        process.exit(0);
-    }
-    const [command, subcommand, ...rest] = positional;
-    // `manifest pull` is kept as an internal/advanced command — not advertised
-    // in HELP, but still callable for users who want pull without the PATCH
-    // step. Prefer `ncblock connect <id>`.
-    if (command === "manifest" && subcommand === "pull") {
-        const idOrUrl = rest[0];
-        if (!idOrUrl) {
-            console.error("Error: missing <id-or-url> argument.\n");
-            console.error("Usage: ncblock manifest pull <id-or-url> [options]");
-            process.exit(1);
-        }
-        pullManifest({
-            idOrUrl,
-            key: flags.key,
-            out: flags.out,
-            dryRun: flags.dryRun,
-            quiet: flags.quiet,
-        });
-        return;
-    }
-    if (command === "connect") {
-        // `ncblock connect <database-url-or-id>` pulls the schema first then
-        // runs the binding/PATCH flow against target.json. The positional
-        // must point at a database (or a data source); ID-kind classification
-        // (block vs view vs wrong-workspace) happens upstream in `init.ts`.
-        connect({
-            idOrUrl: subcommand,
-            blockIds: blocks,
-            bindings,
-            key: flags.key,
-            out: flags.out,
-            manifest: flags.manifest,
-            env: flags.env,
-            dryRun: flags.dryRun,
-            jsonOutput: flags.jsonOutput,
-            quiet: flags.quiet,
-        });
-        return;
-    }
-    if (command === "data_sources" && subcommand === "get") {
-        const idOrUrl = rest[0];
-        if (!idOrUrl) {
-            console.error("Error: missing <block-id-or-url> argument.\n");
-            console.error("Usage: ncblock data_sources get <block-id-or-url>");
-            process.exit(1);
-        }
-        getDataSources(idOrUrl);
-        return;
-    }
-    if (command === "deploy") {
-        const distPath = subcommand;
-        if (!distPath) {
-            console.error("Error: missing <dist-path> argument.\n");
-            console.error("Usage: ncblock deploy <dist-path> [--block <id>...] [--env <name>]");
-            process.exit(1);
-        }
-        deploy({
-            distPath,
-            blockIds: blocks,
-            env: flags.env,
-            dryRun: flags.dryRun,
-            jsonOutput: flags.jsonOutput,
-        });
-        return;
-    }
-    // The commands below route their API calls through ntn.ts, which resolves
-    // the env from `process.env.ENV` (falling back to target.json). Honor an
-    // explicit --env by setting it here so every ntn call inherits it.
-    if (flags.env) {
-        process.env.ENV = flags.env;
-    }
-    if (command === "pull_data") {
-        const idOrUrl = subcommand;
-        if (!idOrUrl) {
-            console.error("Error: missing <id-or-url> argument.\n");
-            console.error("Usage: ncblock pull_data <id-or-url> [--limit <n>] [--out <path>]");
-            process.exit(1);
-        }
-        const limitRaw = flags.limit;
-        const limit = limitRaw === undefined ? undefined : Number(limitRaw);
-        if (limit !== undefined && !Number.isFinite(limit)) {
-            console.error(`Error: --limit must be a number, got '${limitRaw}'.`);
-            process.exit(1);
-        }
-        pullData({
-            idOrUrl,
-            limit,
-            out: flags.out,
-        });
-        return;
-    }
-    if (command === "attach") {
-        const idOrUrl = subcommand;
-        if (!idOrUrl) {
-            console.error("Error: missing <block-id-or-url> argument.\n");
-            console.error("Usage: ncblock attach <block-id-or-url> [--capability <key>]");
-            process.exit(1);
-        }
-        attach({
-            idOrUrl,
-            capability: flags.capability,
-            jsonOutput: flags.jsonOutput,
-        });
-        return;
-    }
-    if (command === "create") {
-        create({
-            parent: flags.parent,
-            capability: flags.capability,
-            jsonOutput: flags.jsonOutput,
-        });
-        return;
-    }
-    console.error(`Unknown command: ${positional.join(" ")}\n`);
-    console.log(HELP);
-    process.exit(1);
-}
-try {
-    main();
-}
-catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    console.error(`\nError: ${message}\n`);
-    process.exit(1);
-}