ntion 0.1.3 → 0.3.0

package/README.md

@@ -35,6 +35,16 @@ A single "get all my tasks" workflow tells the whole story:
 2. **No schema bloat** — MCP's database fetch includes ~2 KB of SQLite DDL, ~800 B of XML boilerplate, and ~1.4 KB of base64 `collectionPropertyOption://` URLs that are never used for reads. ntion returns only actionable data.
 3. **Markdown-first** — Page content defaults to markdown, matching what agents actually consume. No manual format negotiation needed.
 
+### Operations the official MCP can't do
+
+The official Notion MCP server has no block delete tool. ntion does:
+
+```bash
+ntion blocks delete --block-ids <block_id>
+```
+
+Delete one or many blocks in a single call — useful for cleaning up content, removing broken blocks, or precise page editing.
+
 ## Agent skill
 
 ntion ships with an [agent skill](https://docs.anthropic.com/en/docs/claude-code/skills) that teaches AI agents how to use the CLI. Install it with:
@@ -157,6 +167,10 @@ ntion blocks replace-range \
   --start-selector-json '{"where":{"text_contains":"Start"}}' \
   --end-selector-json '{"where":{"text_contains":"End"}}' \
   --markdown "Replacement content"
+
+# Delete blocks (not available in the official Notion MCP)
+ntion blocks delete --block-ids <block_id>
+ntion blocks delete --block-ids <id1> <id2> <id3>
 ```
 
 ### Health check

package/dist/cli.js

@@ -10,7 +10,7 @@ import { getConfigPath } from "./config/paths.js";
 import { buildInitialAuthConfig, loadConfigOrNull, saveConfig } from "./config/store.js";
 import { CliError } from "./errors/cli-error.js";
 import { markdownToBlocks } from "./notion/markdown.js";
-import { appendBlocks, archivePage, createPage, createPagesBulk, getBlocks, getDataSource, getDataSourceSchema, getPage, insertBlocks, listDataSources, queryDataSourcePages, replaceBlockRange, searchWorkspace, selectBlocks, setRelation, unarchivePage, updatePage, } from "./notion/repository.js";
+import { appendBlocks, archivePage, createPage, createPagesBulk, deleteBlocks, getBlocks, getDataSource, getDataSourceSchema, getPage, insertBlocks, listDataSources, queryDataSourcePages, replaceBlockRange, searchWorkspace, selectBlocks, setRelation, unarchivePage, updatePage, } from "./notion/repository.js";
 import { parseJsonOption } from "./utils/json.js";
 const ROOT_HELP_EPILOG = [
     "",
@@ -218,6 +218,7 @@ async function runInteractiveAuthSetup() {
     }
     const rl = createInterface({ input, output });
     try {
+        console.log("Create a token at https://www.notion.so/profile/integrations\n");
         const response = await rl.question("Paste your Notion integration token: ");
         const trimmed = response.trim();
         if (!trimmed) {
@@ -254,9 +255,11 @@ async function saveAuthConfigEnv(tokenEnv) {
         config_path: getConfigPath(),
     };
 }
+const packageJson = JSON.parse(await readFile(new URL("../package.json", import.meta.url), "utf-8"));
 const program = new Command();
 program
     .name("ntion")
+    .version(packageJson.version, "-V, --version", "print version number")
     .description("Token-efficient, workspace-agnostic Notion CLI")
     .showHelpAfterError()
     .addHelpText("after", ROOT_HELP_EPILOG);
@@ -918,6 +921,27 @@ const blocksReplaceRangeCommand = blocksCommand
     });
 });
 blocksReplaceRangeCommand.addHelpText("after", BLOCKS_REPLACE_RANGE_HELP_EPILOG);
+blocksCommand
+    .command("delete")
+    .description("Delete one or more blocks by ID")
+    .requiredOption("--block-ids <ids...>", "Block IDs to delete")
+    .option("--pretty", "pretty-print JSON output")
+    .option("--timeout-ms <n>", "request timeout in milliseconds")
+    .action(async (options) => {
+    await runAction(Boolean(options.pretty), async (requestId) => {
+        const { notion } = await loadRuntime({ timeoutMs: options.timeoutMs });
+        const result = await executeMutationWithIdempotency({
+            commandName: "blocks.delete",
+            requestId,
+            requestShape: { block_ids: options.blockIds },
+            targetIds: options.blockIds,
+            run: () => deleteBlocks(notion, { blockIds: options.blockIds }),
+        });
+        return {
+            data: result,
+        };
+    });
+});
 program
     .command("doctor")
     .description("Validate config and auth quickly")

package/dist/notion/markdown.js

@@ -9,13 +9,142 @@ function chunkText(content) {
     }
     return chunks;
 }
+const DEFAULT_ANNOTATIONS = {
+    bold: false,
+    italic: false,
+    strikethrough: false,
+    code: false,
+};
+function findClosingStar(text, start) {
+    for (let i = start; i < text.length; i++) {
+        if (text[i] === "*" && text[i + 1] !== "*" && text[i - 1] !== "*") {
+            return i;
+        }
+    }
+    return -1;
+}
+function parseInlineSegments(text, inherited, linkUrl) {
+    const segments = [];
+    let i = 0;
+    let plain = "";
+    const flush = () => {
+        if (plain) {
+            segments.push({ content: plain, annotations: { ...inherited }, link: linkUrl });
+            plain = "";
+        }
+    };
+    while (i < text.length) {
+        // Inline code (no nesting inside)
+        if (text[i] === "`") {
+            const close = text.indexOf("`", i + 1);
+            if (close !== -1) {
+                flush();
+                segments.push({
+                    content: text.slice(i + 1, close),
+                    annotations: { ...inherited, code: true },
+                    link: linkUrl,
+                });
+                i = close + 1;
+                continue;
+            }
+        }
+        // Link [text](url)
+        if (text[i] === "[") {
+            const bracketClose = text.indexOf("]", i + 1);
+            if (bracketClose !== -1 && text[bracketClose + 1] === "(") {
+                const parenClose = text.indexOf(")", bracketClose + 2);
+                if (parenClose !== -1) {
+                    flush();
+                    const linkText = text.slice(i + 1, bracketClose);
+                    const url = text.slice(bracketClose + 2, parenClose);
+                    segments.push(...parseInlineSegments(linkText, inherited, url));
+                    i = parenClose + 1;
+                    continue;
+                }
+            }
+        }
+        // *** bold+italic
+        if (text[i] === "*" && text[i + 1] === "*" && text[i + 2] === "*") {
+            const close = text.indexOf("***", i + 3);
+            if (close !== -1) {
+                flush();
+                segments.push(...parseInlineSegments(text.slice(i + 3, close), { ...inherited, bold: true, italic: true }, linkUrl));
+                i = close + 3;
+                continue;
+            }
+        }
+        // ** bold
+        if (text[i] === "*" && text[i + 1] === "*") {
+            const close = text.indexOf("**", i + 2);
+            if (close !== -1) {
+                flush();
+                segments.push(...parseInlineSegments(text.slice(i + 2, close), { ...inherited, bold: true }, linkUrl));
+                i = close + 2;
+                continue;
+            }
+        }
+        // * italic
+        if (text[i] === "*") {
+            const close = findClosingStar(text, i + 1);
+            if (close !== -1) {
+                flush();
+                segments.push(...parseInlineSegments(text.slice(i + 1, close), { ...inherited, italic: true }, linkUrl));
+                i = close + 1;
+                continue;
+            }
+        }
+        // ~~ strikethrough
+        if (text[i] === "~" && text[i + 1] === "~") {
+            const close = text.indexOf("~~", i + 2);
+            if (close !== -1) {
+                flush();
+                segments.push(...parseInlineSegments(text.slice(i + 2, close), { ...inherited, strikethrough: true }, linkUrl));
+                i = close + 2;
+                continue;
+            }
+        }
+        plain += text[i];
+        i++;
+    }
+    flush();
+    return segments;
+}
+function segmentToRichText(segment) {
+    return chunkText(segment.content).map((chunk) => {
+        const textObj = { content: chunk };
+        if (segment.link) {
+            textObj.link = { url: segment.link };
+        }
+        const obj = { type: "text", text: textObj };
+        const { bold, italic, strikethrough, code } = segment.annotations;
+        if (bold || italic || strikethrough || code) {
+            const annotations = {};
+            if (bold)
+                annotations.bold = true;
+            if (italic)
+                annotations.italic = true;
+            if (strikethrough)
+                annotations.strikethrough = true;
+            if (code)
+                annotations.code = true;
+            obj.annotations = annotations;
+        }
+        return obj;
+    });
+}
 function toRichText(content) {
+    const normalized = content.length > 0 ? content : " ";
+    const segments = parseInlineSegments(normalized, DEFAULT_ANNOTATIONS);
+    if (segments.length === 0) {
+        return [{ type: "text", text: { content: " " } }];
+    }
+    return segments.flatMap(segmentToRichText);
+}
+function toPlainRichText(content) {
     const normalized = content.length > 0 ? content : " ";
     return chunkText(normalized).map((chunk) => ({
         type: "text",
-        text: {
-            content: chunk,
-        },
+        text: { content: chunk },
     }));
 }
 function paragraphBlock(text) {
@@ -131,11 +260,71 @@ function codeBlock(text, language) {
         object: "block",
         type: "code",
         code: {
-            rich_text: toRichText(text),
+            rich_text: toPlainRichText(text),
             language,
         },
     };
 }
+function imageBlock(url, caption) {
+    return {
+        object: "block",
+        type: "image",
+        image: {
+            type: "external",
+            external: { url },
+            caption: toRichText(caption),
+        },
+    };
+}
+function parseMarkdownTable(lines, startIndex) {
+    const tableLines = [];
+    let i = startIndex;
+    while (i < lines.length && lines[i].trim().includes("|")) {
+        tableLines.push(lines[i].trim());
+        i++;
+    }
+    const linesConsumed = tableLines.length;
+    const parseCells = (line) => {
+        let stripped = line;
+        if (stripped.startsWith("|"))
+            stripped = stripped.slice(1);
+        if (stripped.endsWith("|"))
+            stripped = stripped.slice(0, -1);
+        return stripped.split("|").map((c) => c.trim());
+    };
+    const isSeparator = (line) => {
+        const cells = parseCells(line);
+        return cells.every((c) => /^[-:]+$/.test(c));
+    };
+    const hasColumnHeader = tableLines.length >= 2 && isSeparator(tableLines[1]);
+    const dataLines = tableLines.filter((_, idx) => !(hasColumnHeader && idx === 1));
+    const tableWidth = dataLines.length > 0 ? parseCells(dataLines[0]).length : 0;
+    const children = dataLines.map((line) => {
+        const cells = parseCells(line);
+        while (cells.length < tableWidth)
+            cells.push("");
+        return {
+            object: "block",
+            type: "table_row",
+            table_row: {
+                cells: cells.slice(0, tableWidth).map((c) => toRichText(c)),
+            },
+        };
+    });
+    return {
+        block: {
+            object: "block",
+            type: "table",
+            table: {
+                table_width: tableWidth,
+                has_column_header: hasColumnHeader,
+                has_row_header: false,
+                children,
+            },
+        },
+        linesConsumed,
+    };
+}
 function isDivider(trimmed) {
     return trimmed === "---" || trimmed === "***" || trimmed === "___";
 }
@@ -183,6 +372,20 @@ export function markdownToBlocks(markdown) {
             index += 1;
             continue;
         }
+        const imageMatch = trimmed.match(/^!\[([^\]]*)\]\(([^)]+)\)$/);
+        if (imageMatch) {
+            flushParagraph();
+            blocks.push(imageBlock(imageMatch[2], imageMatch[1]));
+            index += 1;
+            continue;
+        }
+        if (trimmed.startsWith("|")) {
+            flushParagraph();
+            const result = parseMarkdownTable(lines, index);
+            blocks.push(result.block);
+            index += result.linesConsumed;
+            continue;
+        }
         const headingMatch = trimmed.match(/^(#{1,3})\s+(.+)$/);
         if (headingMatch) {
             flushParagraph();

package/dist/notion/repository.d.ts

@@ -140,3 +140,6 @@ export declare function replaceBlockRange(notion: NotionClientAdapter, args: {
     dryRun: boolean;
     maxBlocks: number;
 }): Promise<Record<string, unknown>>;
+export declare function deleteBlocks(notion: NotionClientAdapter, args: {
+    blockIds: string[];
+}): Promise<Record<string, unknown>>;

package/dist/notion/repository.js

@@ -455,6 +455,54 @@ function extractBlockText(block) {
     })
         .join("");
 }
+function richTextToMarkdown(richTextArray) {
+    return richTextArray
+        .map((item) => {
+        if (!item || typeof item !== "object")
+            return "";
+        const plain = item.plain_text;
+        if (typeof plain !== "string")
+            return "";
+        const annotations = item.annotations;
+        const href = item.href ??
+            (item.text?.link?.url ?? null);
+        let result = plain;
+        if (annotations?.code) {
+            result = `\`${result}\``;
+        }
+        else {
+            if (annotations?.bold && annotations?.italic) {
+                result = `***${result}***`;
+            }
+            else if (annotations?.bold) {
+                result = `**${result}**`;
+            }
+            else if (annotations?.italic) {
+                result = `*${result}*`;
+            }
+            if (annotations?.strikethrough) {
+                result = `~~${result}~~`;
+            }
+        }
+        if (typeof href === "string") {
+            result = `[${result}](${href})`;
+        }
+        return result;
+    })
+        .join("");
+}
+function extractBlockMarkdown(block) {
+    const type = block.type;
+    if (typeof type !== "string")
+        return null;
+    const typedData = block[type];
+    if (!typedData || typeof typedData !== "object")
+        return null;
+    const richText = typedData.rich_text;
+    if (!Array.isArray(richText))
+        return null;
+    return richTextToMarkdown(richText);
+}
 function toCompactBlock(block) {
     return {
         id: block.id ?? null,
@@ -508,7 +556,7 @@ function renderQuoteMarkdown(text, indent) {
 }
 function renderBlockToMarkdown(block, depth) {
     const type = typeof block.type === "string" ? block.type : "unsupported";
-    const text = extractBlockText(block) ?? "";
+    const text = extractBlockMarkdown(block) ?? "";
     const indent = "  ".repeat(depth);
     const children = collectRenderableChildren(block);
     const childMarkdown = children.length > 0 ? renderBlocksToMarkdown(children, depth + 1) : "";
@@ -557,6 +605,41 @@ function renderBlockToMarkdown(block, depth) {
         }
         case "toggle":
             return withChildren(`${indent}- ${text}`, true);
+        case "image": {
+            const img = block.image;
+            let imgUrl = "";
+            if (img) {
+                if (img.type === "external") {
+                    const ext = img.external;
+                    imgUrl = ext?.url ?? "";
+                }
+                else {
+                    const file = img.file;
+                    imgUrl = file?.url ?? "";
+                }
+            }
+            const caption = img && Array.isArray(img.caption) ? richTextToMarkdown(img.caption) : "";
+            return withChildren(`${indent}![${caption}](${imgUrl})`);
+        }
+        case "table": {
+            const tbl = block.table;
+            const rows = children;
+            const rowLines = [];
+            for (let ri = 0; ri < rows.length; ri++) {
+                const row = rows[ri];
+                const tr = row.table_row;
+                if (!tr?.cells)
+                    continue;
+                const cellTexts = tr.cells.map((cell) => richTextToMarkdown(cell).replace(/\|/g, "\\|"));
+                rowLines.push(`${indent}| ${cellTexts.join(" | ")} |`);
+                if (ri === 0 && tbl?.has_column_header) {
+                    rowLines.push(`${indent}| ${cellTexts.map(() => "---").join(" | ")} |`);
+                }
+            }
+            return rowLines.join("\n");
+        }
+        case "table_row":
+            return "";
         default: {
             const fallback = text.length > 0 ? text : `[${type}]`;
             return withChildren(`${indent}${fallback}`);
@@ -996,3 +1079,14 @@ export async function replaceBlockRange(notion, args) {
         deleted_count: blocksToDelete.length,
     };
 }
+export async function deleteBlocks(notion, args) {
+    const deletedIds = [];
+    for (const blockId of args.blockIds) {
+        await notion.deleteBlock({ block_id: blockId });
+        deletedIds.push(blockId);
+    }
+    return {
+        deleted_count: deletedIds.length,
+        deleted_ids: deletedIds,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ntion",
-  "version": "0.1.3",
+  "version": "0.3.0",
   "description": "Token-efficient CLI for personal Notion workspaces",
   "type": "module",
   "license": "MIT",