ntion 0.2.0 → 0.4.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:
@@ -138,9 +148,11 @@ ntion pages unrelate --from-id <page_id> --property Project --to-id <page_id>
 ```bash
 # Read as markdown (default)
 ntion blocks get --id <page_or_block_id> --depth 1
+ntion blocks get --id <page_or_block_id> --view full
+# blocks get uses --view (markdown|compact|full)
 
 # Append markdown content
-ntion blocks append --id <page_or_block_id> --markdown "# Title\n\nHello"
+ntion blocks append --id <page_or_block_id> --markdown $'# Title\n\nHello'
 ntion blocks append --id <page_or_block_id> --markdown-file ./notes.md
 
 # Surgical insertion
@@ -157,6 +169,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
@@ -183,7 +199,7 @@ Compact, deterministic, easy to parse — by humans or machines.
 
 - **Generic** — works with any Notion workspace, no hardcoded schema assumptions
 - **Compact** — deterministic JSON envelopes, minimal bytes per response
-- **Safe** — automatic idempotency for all mutations, built-in conflict detection
+- **Safe** — automatic idempotency for all mutations, built-in conflict detection and verify-first recovery
 - **Fast** — zero native dependencies, internal schema caching, batch operations
 - **Agent-friendly** — designed for AI agents that pay per token
 

package/dist/audit/log.d.ts

@@ -6,5 +6,9 @@ export interface AuditEvent {
     target_ids?: string[];
     ok: boolean;
     timestamp: string;
+    recovery_attempted?: boolean;
+    recovery_succeeded?: boolean;
+    idempotency_persist_degraded?: boolean;
+    outcome_uncertain?: boolean;
 }
 export declare function appendAuditLog(event: AuditEvent): Promise<void>;

package/dist/cli.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { readFile } from "node:fs/promises";
-import { Command } from "commander";
+import { Command, Option } from "commander";
 import { createInterface } from "node:readline/promises";
 import { stdin as input, stdout as output } from "node:process";
 import { executeMutationWithIdempotency } from "./commands/mutation.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, areBlocksDeleted, 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 = [
     "",
@@ -59,9 +59,15 @@ const BLOCKS_APPEND_HELP_EPILOG = [
     "  Provide exactly one of --blocks-json, --markdown, or --markdown-file.",
     "",
     "Examples:",
-    "  ntion blocks append --id <id> --markdown \"# Heading\\n\\nBody\"",
+    "  ntion blocks append --id <id> --markdown $'# Heading\\n\\nBody'",
     "  ntion blocks append --id <id> --markdown-file ./notes.md",
 ].join("\n");
+const BLOCKS_GET_HELP_EPILOG = [
+    "",
+    "View vs Return-View:",
+    "  blocks get uses --view <markdown|compact|full>.",
+    "  mutation commands use --return-view <compact|full> for page/data outputs.",
+].join("\n");
 const BLOCKS_INSERT_HELP_EPILOG = [
     "",
     "Positioning:",
@@ -104,7 +110,7 @@ function resolveBlockReadFormat(input, fallback) {
     if (value === "markdown" || value === "compact" || value === "full") {
         return value;
     }
-    throw new CliError("invalid_input", "Block format must be markdown, compact, or full.");
+    throw new CliError("invalid_input", "Block view must be markdown, compact, or full.");
 }
 function parseSearchObject(raw) {
     if (!raw) {
@@ -188,11 +194,26 @@ async function resolveBlocksInput(args) {
         return requireArrayJson(args.blocksJson, "blocks-json");
     }
     if (args.markdown) {
+        validateMarkdownInput(args.markdown);
         return markdownToBlocks(args.markdown);
     }
     const markdown = await readFile(String(args.markdownFile), "utf8");
     return markdownToBlocks(markdown);
 }
+function validateMarkdownInput(markdown) {
+    if (markdown.includes("\\n") && !markdown.includes("\n")) {
+        throw new CliError("invalid_input", "--markdown appears to contain literal \\n escapes. Use real newline characters or --markdown-file.");
+    }
+}
+function relationIncludesTarget(page, propertyName, targetId) {
+    const properties = page.properties;
+    if (!properties || typeof properties !== "object") {
+        return false;
+    }
+    const relationValue = properties[propertyName];
+    return (Array.isArray(relationValue) &&
+        relationValue.some((value) => typeof value === "string" && value === targetId));
+}
 function addCommonReadOptions(command) {
     return command
         .option("--view <compact|full>", "response view mode")
@@ -218,6 +239,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 +276,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);
@@ -611,6 +635,16 @@ addCommonMutationOptions(pagesCommand.command("archive").description("Archive a
                 view,
                 fields,
             }),
+            recover: async () => {
+                const current = await getPage(notion, options.id, "full");
+                if (current.archived !== true) {
+                    return null;
+                }
+                if (view === "full") {
+                    return current;
+                }
+                return getPage(notion, options.id, view, fields);
+            },
         });
         return {
             data: {
@@ -644,6 +678,16 @@ addCommonMutationOptions(pagesCommand.command("unarchive").description("Unarchiv
                 view,
                 fields,
             }),
+            recover: async () => {
+                const current = await getPage(notion, options.id, "full");
+                if (current.archived !== false) {
+                    return null;
+                }
+                if (view === "full") {
+                    return current;
+                }
+                return getPage(notion, options.id, view, fields);
+            },
         });
         return {
             data: {
@@ -684,6 +728,16 @@ addCommonMutationOptions(pagesCommand.command("relate").description("Add a relat
                 view,
                 fields,
             }),
+            recover: async () => {
+                const current = await getPage(notion, options.fromId, "full");
+                if (!relationIncludesTarget(current, options.property, options.toId)) {
+                    return null;
+                }
+                if (view === "full") {
+                    return current;
+                }
+                return getPage(notion, options.fromId, view, fields);
+            },
         });
         return {
             data: {
@@ -724,6 +778,16 @@ addCommonMutationOptions(pagesCommand.command("unrelate").description("Remove a
                 view,
                 fields,
             }),
+            recover: async () => {
+                const current = await getPage(notion, options.fromId, "full");
+                if (relationIncludesTarget(current, options.property, options.toId)) {
+                    return null;
+                }
+                if (view === "full") {
+                    return current;
+                }
+                return getPage(notion, options.fromId, view, fields);
+            },
         });
         return {
             data: {
@@ -733,27 +797,32 @@ addCommonMutationOptions(pagesCommand.command("unrelate").description("Remove a
     });
 });
 const blocksCommand = program.command("blocks").description("Block operations");
-blocksCommand
+const blocksGetCommand = blocksCommand
     .command("get")
     .description("Get blocks from a page or block")
     .requiredOption("--id <page_or_block_id>", "Notion page or block ID")
     .option("--max-blocks <n>", "Maximum block count")
     .option("--depth <n>", "Recursion depth", "1")
-    .option("--format <markdown|compact|full>", "content format", "markdown")
+    .option("--view <markdown|compact|full>", "content view", "markdown")
+    .addOption(new Option("--format <markdown|compact|full>").hideHelp())
     .option("--pretty", "pretty-print JSON output")
     .option("--timeout-ms <n>", "request timeout in milliseconds")
     .action(async (options) => {
     await runAction(Boolean(options.pretty), async () => {
+        if (options.format) {
+            throw new CliError("invalid_input", "--format is no longer supported for blocks get. Use --view <markdown|compact|full>.");
+        }
         const { config, notion } = await loadRuntime({ timeoutMs: options.timeoutMs });
         const maxBlocks = parsePositiveInt(options.maxBlocks, "max-blocks", config.defaults.max_blocks);
         const depth = parsePositiveInt(options.depth, "depth", 1);
-        const format = resolveBlockReadFormat(options.format, "markdown");
-        const blocks = await getBlocks(notion, options.id, maxBlocks, depth, format);
+        const view = resolveBlockReadFormat(options.view, "markdown");
+        const blocks = await getBlocks(notion, options.id, maxBlocks, depth, view);
         return {
             data: blocks,
         };
     });
 });
+blocksGetCommand.addHelpText("after", BLOCKS_GET_HELP_EPILOG);
 const blocksAppendCommand = blocksCommand
     .command("append")
     .description("Append blocks to a page or block")
@@ -766,12 +835,12 @@ const blocksAppendCommand = blocksCommand
     .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 blocks = await resolveBlocksInput({
             blocksJson: options.blocksJson,
             markdown: options.markdown,
             markdownFile: options.markdownFile,
         });
+        const { notion } = await loadRuntime({ timeoutMs: options.timeoutMs });
         const result = await executeMutationWithIdempotency({
             commandName: options.dryRun ? "blocks.append.dry_run" : "blocks.append",
             requestId,
@@ -807,13 +876,13 @@ const blocksInsertCommand = blocksCommand
     .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 blocks = await resolveBlocksInput({
             blocksJson: options.blocksJson,
             markdown: options.markdown,
             markdownFile: options.markdownFile,
         });
         const position = resolveInsertPosition(options.position, options.afterId);
+        const { notion } = await loadRuntime({ timeoutMs: options.timeoutMs });
         const result = await executeMutationWithIdempotency({
             commandName: options.dryRun ? "blocks.insert.dry_run" : "blocks.insert",
             requestId,
@@ -878,7 +947,6 @@ const blocksReplaceRangeCommand = blocksCommand
     .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 blocks = await resolveBlocksInput({
             blocksJson: options.blocksJson,
             markdown: options.markdown,
@@ -887,6 +955,7 @@ const blocksReplaceRangeCommand = blocksCommand
         const startSelector = requireSelectorJson(options.startSelectorJson, "start-selector-json");
         const endSelector = requireSelectorJson(options.endSelectorJson, "end-selector-json");
         const maxBlocks = parsePositiveInt(options.scanMaxBlocks, "scan-max-blocks", 5000);
+        const { notion } = await loadRuntime({ timeoutMs: options.timeoutMs });
         const result = await executeMutationWithIdempotency({
             commandName: options.dryRun ? "blocks.replace_range.dry_run" : "blocks.replace_range",
             requestId,
@@ -918,6 +987,37 @@ 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 }),
+            recover: async () => {
+                const deleted = await areBlocksDeleted(notion, options.blockIds);
+                if (!deleted) {
+                    return null;
+                }
+                return {
+                    deleted_count: options.blockIds.length,
+                    deleted_ids: options.blockIds,
+                };
+            },
+        });
+        return {
+            data: result,
+        };
+    });
+});
 program
     .command("doctor")
     .description("Validate config and auth quickly")

package/dist/commands/mutation.d.ts

@@ -5,4 +5,6 @@ export declare function executeMutationWithIdempotency<T>(args: {
     entity?: string;
     targetIds?: string[];
     run: () => Promise<T>;
+    recover?: () => Promise<T | null>;
+    isAmbiguousError?: (error: unknown) => boolean;
 }): Promise<T>;

package/dist/commands/mutation.js

@@ -13,11 +13,42 @@ async function safeAppendAuditLog(event) {
         // Audit logging must not alter mutation outcomes.
     }
 }
+function getStatus(error) {
+    if (!error || typeof error !== "object") {
+        return undefined;
+    }
+    const status = error.status;
+    return typeof status === "number" ? status : undefined;
+}
+function getCode(error) {
+    if (!error || typeof error !== "object") {
+        return undefined;
+    }
+    const code = error.code;
+    return typeof code === "string" ? code : undefined;
+}
+function isAmbiguousMutationError(error, override) {
+    if (override) {
+        return override(error);
+    }
+    if (error instanceof CliError && error.code === "retryable_upstream") {
+        return true;
+    }
+    const status = getStatus(error);
+    if (status === 429 || (typeof status === "number" && status >= 500)) {
+        return true;
+    }
+    return getCode(error) === "internal_error";
+}
 export async function executeMutationWithIdempotency(args) {
     const store = new IdempotencyStore();
     const requestHash = hashObject(args.requestShape);
     const idempotencyKey = buildInternalIdempotencyKey(args.commandName, args.requestShape);
     let ownsReservation = false;
+    let recoveryAttempted = false;
+    let recoverySucceeded = false;
+    let idempotencyPersistDegraded = false;
+    let outcomeUncertain = false;
     try {
         let lookup = store.reserve(idempotencyKey, args.commandName, requestHash);
         while (lookup.kind === "pending") {
@@ -68,8 +99,45 @@ export async function executeMutationWithIdempotency(args) {
             return lookup.response;
         }
         ownsReservation = true;
-        const response = await args.run();
-        store.complete(idempotencyKey, args.commandName, requestHash, response);
+        let response;
+        try {
+            response = await args.run();
+        }
+        catch (error) {
+            if (!isAmbiguousMutationError(error, args.isAmbiguousError)) {
+                throw error;
+            }
+            recoveryAttempted = true;
+            if (args.recover) {
+                try {
+                    const recovered = await args.recover();
+                    if (recovered !== null) {
+                        response = recovered;
+                        recoverySucceeded = true;
+                    }
+                    else {
+                        outcomeUncertain = true;
+                        throw new CliError("retryable_upstream", "Mutation outcome could not be confirmed. Re-read before retrying.", { retryable: true });
+                    }
+                }
+                catch {
+                    outcomeUncertain = true;
+                    throw new CliError("retryable_upstream", "Mutation outcome could not be confirmed. Re-read before retrying.", { retryable: true });
+                }
+            }
+            else {
+                outcomeUncertain = true;
+                throw new CliError("retryable_upstream", "Mutation outcome could not be confirmed. Re-read before retrying.", { retryable: true });
+            }
+        }
+        try {
+            store.complete(idempotencyKey, args.commandName, requestHash, response);
+        }
+        catch {
+            // Avoid surfacing internal idempotency persistence failures to callers
+            // after the write has already succeeded or been verified.
+            idempotencyPersistDegraded = true;
+        }
         await safeAppendAuditLog({
             command: args.commandName,
             entity: args.entity,
@@ -77,6 +145,10 @@ export async function executeMutationWithIdempotency(args) {
             idempotency_key: idempotencyKey,
             target_ids: args.targetIds,
             ok: true,
+            recovery_attempted: recoveryAttempted,
+            recovery_succeeded: recoverySucceeded,
+            idempotency_persist_degraded: idempotencyPersistDegraded,
+            outcome_uncertain: false,
             timestamp: new Date().toISOString(),
         });
         return response;
@@ -92,6 +164,10 @@ export async function executeMutationWithIdempotency(args) {
             idempotency_key: idempotencyKey,
             target_ids: args.targetIds,
             ok: false,
+            recovery_attempted: recoveryAttempted,
+            recovery_succeeded: recoverySucceeded,
+            idempotency_persist_degraded: idempotencyPersistDegraded,
+            outcome_uncertain: outcomeUncertain,
             timestamp: new Date().toISOString(),
         });
         throw error;

package/dist/config/paths.d.ts

@@ -2,4 +2,5 @@ export declare function getConfigDir(): string;
 export declare function getConfigPath(): string;
 export declare function getAuditLogPath(): string;
 export declare function getIdempotencyStorePath(): string;
+export declare function getIdempotencyLockPath(): string;
 export declare function ensureConfigDir(): string;

package/dist/config/paths.js

@@ -17,6 +17,9 @@ export function getAuditLogPath() {
 export function getIdempotencyStorePath() {
     return join(getConfigDir(), "idempotency.json");
 }
+export function getIdempotencyLockPath() {
+    return join(getConfigDir(), "idempotency.lock");
+}
 export function ensureConfigDir() {
     const configDir = getConfigDir();
     if (!existsSync(configDir)) {

package/dist/idempotency/store.d.ts

@@ -22,13 +22,19 @@ export type IdempotencyReservation = {
 };
 export declare class IdempotencyStore {
     private readonly filePath;
+    private readonly lockPath;
     constructor(filePath?: string);
     close(): void;
     lookup(idempotencyKey: string, commandName: string, inputHash: string): IdempotencyLookup;
     reserve(idempotencyKey: string, commandName: string, inputHash: string): IdempotencyReservation;
     complete(idempotencyKey: string, commandName: string, inputHash: string, response: unknown): void;
     release(idempotencyKey: string, commandName: string, inputHash: string): void;
-    private loadData;
-    private saveData;
+    private withLock;
+    private acquireLock;
+    private releaseLock;
+    private tryClearStaleLock;
+    private sleepMs;
+    private loadDataUnlocked;
+    private saveDataUnlocked;
 }
 export declare function buildInternalIdempotencyKey(commandName: string, requestShape: unknown): string;

package/dist/idempotency/store.js

@@ -1,87 +1,172 @@
-import { readFileSync, writeFileSync } from "node:fs";
-import { ensureConfigDir, getIdempotencyStorePath } from "../config/paths.js";
+import { closeSync, openSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync, } from "node:fs";
+import { ensureConfigDir, getIdempotencyLockPath, getIdempotencyStorePath } from "../config/paths.js";
 import { CliError } from "../errors/cli-error.js";
 import { hashObject } from "../utils/json.js";
 const PRUNE_TTL_MS = 180_000;
+const LOCK_STALE_MS = 30_000;
+const LOCK_WAIT_TIMEOUT_MS = 35_000;
+const LOCK_POLL_INTERVAL_MS = 30;
+const SLEEP_ARRAY = new Int32Array(new SharedArrayBuffer(4));
 const PENDING_RESPONSE_JSON = JSON.stringify({ __notion_lite_pending: true });
 function compositeKey(idempotencyKey, commandName) {
     return `${idempotencyKey}\0${commandName}`;
 }
 export class IdempotencyStore {
     filePath;
+    lockPath;
     constructor(filePath = getIdempotencyStorePath()) {
         ensureConfigDir();
         this.filePath = filePath;
+        this.lockPath =
+            filePath === getIdempotencyStorePath() ? getIdempotencyLockPath() : `${filePath}.lock`;
     }
     close() {
         // no-op — nothing to tear down for a JSON file store
     }
     lookup(idempotencyKey, commandName, inputHash) {
-        const data = this.loadData();
-        const entry = data[compositeKey(idempotencyKey, commandName)];
-        if (!entry) {
-            return { kind: "miss" };
-        }
-        if (entry.inputHash !== inputHash) {
-            return { kind: "conflict", storedHash: entry.inputHash };
-        }
-        if (entry.responseJson === PENDING_RESPONSE_JSON) {
-            return { kind: "pending" };
-        }
+        return this.withLock(() => {
+            const data = this.loadDataUnlocked();
+            const entry = data[compositeKey(idempotencyKey, commandName)];
+            if (!entry) {
+                return { kind: "miss" };
+            }
+            if (entry.inputHash !== inputHash) {
+                return { kind: "conflict", storedHash: entry.inputHash };
+            }
+            if (entry.responseJson === PENDING_RESPONSE_JSON) {
+                return { kind: "pending" };
+            }
+            try {
+                return { kind: "replay", response: JSON.parse(entry.responseJson) };
+            }
+            catch {
+                throw new CliError("internal_error", "Stored idempotency response is corrupt.");
+            }
+        });
+    }
+    reserve(idempotencyKey, commandName, inputHash) {
+        return this.withLock(() => {
+            const data = this.loadDataUnlocked();
+            const key = compositeKey(idempotencyKey, commandName);
+            if (!data[key]) {
+                data[key] = {
+                    inputHash,
+                    responseJson: PENDING_RESPONSE_JSON,
+                    createdAt: Date.now(),
+                };
+                this.saveDataUnlocked(data);
+                return { kind: "execute" };
+            }
+            const entry = data[key];
+            if (entry.inputHash !== inputHash) {
+                return { kind: "conflict", storedHash: entry.inputHash };
+            }
+            if (entry.responseJson === PENDING_RESPONSE_JSON) {
+                return { kind: "pending" };
+            }
+            try {
+                return { kind: "replay", response: JSON.parse(entry.responseJson) };
+            }
+            catch {
+                throw new CliError("internal_error", "Stored idempotency response is corrupt.");
+            }
+        });
+    }
+    complete(idempotencyKey, commandName, inputHash, response) {
+        this.withLock(() => {
+            const data = this.loadDataUnlocked();
+            const key = compositeKey(idempotencyKey, commandName);
+            const entry = data[key];
+            if (!entry) {
+                data[key] = {
+                    inputHash,
+                    responseJson: JSON.stringify(response),
+                    createdAt: Date.now(),
+                };
+                this.saveDataUnlocked(data);
+                return;
+            }
+            if (entry.inputHash !== inputHash) {
+                throw new CliError("internal_error", "Failed to finalize idempotency record for mutation replay.");
+            }
+            entry.responseJson = JSON.stringify(response);
+            entry.createdAt = Date.now();
+            this.saveDataUnlocked(data);
+        });
+    }
+    release(idempotencyKey, commandName, inputHash) {
+        this.withLock(() => {
+            const data = this.loadDataUnlocked();
+            const key = compositeKey(idempotencyKey, commandName);
+            const entry = data[key];
+            if (entry && entry.inputHash === inputHash && entry.responseJson === PENDING_RESPONSE_JSON) {
+                delete data[key];
+                this.saveDataUnlocked(data);
+            }
+        });
+    }
+    withLock(fn) {
+        const lockFd = this.acquireLock();
         try {
-            return { kind: "replay", response: JSON.parse(entry.responseJson) };
+            return fn();
         }
-        catch {
-            throw new CliError("internal_error", "Stored idempotency response is corrupt.");
+        finally {
+            this.releaseLock(lockFd);
         }
     }
-    reserve(idempotencyKey, commandName, inputHash) {
-        const data = this.loadData();
-        const key = compositeKey(idempotencyKey, commandName);
-        if (!data[key]) {
-            data[key] = {
-                inputHash,
-                responseJson: PENDING_RESPONSE_JSON,
-                createdAt: Date.now(),
-            };
-            this.saveData(data);
-            return { kind: "execute" };
+    acquireLock() {
+        const deadline = Date.now() + LOCK_WAIT_TIMEOUT_MS;
+        while (Date.now() < deadline) {
+            try {
+                const fd = openSync(this.lockPath, "wx");
+                writeFileSync(fd, `${JSON.stringify({ pid: process.pid, created_at: new Date().toISOString() })}\n`, "utf-8");
+                return fd;
+            }
+            catch (error) {
+                const code = error.code;
+                if (code !== "EEXIST") {
+                    throw new CliError("internal_error", "Failed to acquire idempotency store lock.", {
+                        details: error,
+                    });
+                }
+                this.tryClearStaleLock();
+                this.sleepMs(LOCK_POLL_INTERVAL_MS + Math.floor(Math.random() * 20));
+            }
         }
-        const entry = data[key];
-        if (entry.inputHash !== inputHash) {
-            return { kind: "conflict", storedHash: entry.inputHash };
+        throw new CliError("retryable_upstream", "Idempotency store is busy. Retry shortly.", {
+            retryable: true,
+        });
+    }
+    releaseLock(lockFd) {
+        try {
+            closeSync(lockFd);
         }
-        if (entry.responseJson === PENDING_RESPONSE_JSON) {
-            return { kind: "pending" };
+        catch {
+            // best effort
         }
         try {
-            return { kind: "replay", response: JSON.parse(entry.responseJson) };
+            unlinkSync(this.lockPath);
         }
         catch {
-            throw new CliError("internal_error", "Stored idempotency response is corrupt.");
+            // best effort
         }
     }
-    complete(idempotencyKey, commandName, inputHash, response) {
-        const data = this.loadData();
-        const key = compositeKey(idempotencyKey, commandName);
-        const entry = data[key];
-        if (!entry || entry.inputHash !== inputHash) {
-            throw new CliError("internal_error", "Failed to finalize idempotency record for mutation replay.");
+    tryClearStaleLock() {
+        try {
+            const lockStat = statSync(this.lockPath);
+            const ageMs = Date.now() - lockStat.mtimeMs;
+            if (ageMs > LOCK_STALE_MS) {
+                unlinkSync(this.lockPath);
+            }
         }
-        entry.responseJson = JSON.stringify(response);
-        entry.createdAt = Date.now();
-        this.saveData(data);
-    }
-    release(idempotencyKey, commandName, inputHash) {
-        const data = this.loadData();
-        const key = compositeKey(idempotencyKey, commandName);
-        const entry = data[key];
-        if (entry && entry.inputHash === inputHash && entry.responseJson === PENDING_RESPONSE_JSON) {
-            delete data[key];
-            this.saveData(data);
+        catch {
+            // best effort
         }
     }
-    loadData() {
+    sleepMs(ms) {
+        Atomics.wait(SLEEP_ARRAY, 0, 0, ms);
+    }
+    loadDataUnlocked() {
         let raw;
         try {
             raw = readFileSync(this.filePath, "utf-8");
@@ -94,6 +179,7 @@ export class IdempotencyStore {
             data = JSON.parse(raw);
         }
         catch {
+            this.saveDataUnlocked({});
             return {};
         }
         const now = Date.now();
@@ -105,12 +191,14 @@ export class IdempotencyStore {
             }
         }
         if (pruned) {
-            this.saveData(data);
+            this.saveDataUnlocked(data);
         }
         return data;
     }
-    saveData(data) {
-        writeFileSync(this.filePath, JSON.stringify(data), "utf-8");
+    saveDataUnlocked(data) {
+        const tempPath = `${this.filePath}.tmp-${process.pid}-${Date.now()}-${Math.random().toString(16).slice(2)}`;
+        writeFileSync(tempPath, JSON.stringify(data), "utf-8");
+        renameSync(tempPath, this.filePath);
     }
 }
 export function buildInternalIdempotencyKey(commandName, requestShape) {

package/dist/notion/markdown.js

@@ -265,6 +265,66 @@ function codeBlock(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 === "___";
 }
@@ -312,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,7 @@ 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>>;
+export declare function areBlocksDeleted(notion: NotionClientAdapter, blockIds: string[]): Promise<boolean>;

package/dist/notion/repository.js

@@ -107,6 +107,94 @@ function readRelationProperty(page, propertyName) {
         .map((item) => item.id)
         .filter((value) => typeof value === "string" && value.length > 0);
 }
+function collectFilterPropertyRefs(value, refs) {
+    if (!value || typeof value !== "object") {
+        return;
+    }
+    if (Array.isArray(value)) {
+        for (const item of value) {
+            collectFilterPropertyRefs(item, refs);
+        }
+        return;
+    }
+    const record = value;
+    if (typeof record.property === "string" && record.property.length > 0) {
+        refs.add(record.property);
+    }
+    for (const child of Object.values(record)) {
+        collectFilterPropertyRefs(child, refs);
+    }
+}
+function levenshteinDistance(a, b) {
+    const left = a.toLowerCase();
+    const right = b.toLowerCase();
+    if (left === right) {
+        return 0;
+    }
+    const matrix = Array.from({ length: left.length + 1 }, () => new Array(right.length + 1).fill(0));
+    for (let i = 0; i <= left.length; i += 1) {
+        matrix[i][0] = i;
+    }
+    for (let j = 0; j <= right.length; j += 1) {
+        matrix[0][j] = j;
+    }
+    for (let i = 1; i <= left.length; i += 1) {
+        for (let j = 1; j <= right.length; j += 1) {
+            const cost = left[i - 1] === right[j - 1] ? 0 : 1;
+            matrix[i][j] = Math.min(matrix[i - 1][j] + 1, matrix[i][j - 1] + 1, matrix[i - 1][j - 1] + cost);
+        }
+    }
+    return matrix[left.length][right.length];
+}
+function suggestPropertyNames(raw, candidates) {
+    const target = raw.toLowerCase();
+    return [...candidates]
+        .sort((a, b) => {
+        const aLower = a.toLowerCase();
+        const bLower = b.toLowerCase();
+        const aStarts = aLower.startsWith(target) ? 0 : 1;
+        const bStarts = bLower.startsWith(target) ? 0 : 1;
+        if (aStarts !== bStarts) {
+            return aStarts - bStarts;
+        }
+        const aContains = aLower.includes(target) ? 0 : 1;
+        const bContains = bLower.includes(target) ? 0 : 1;
+        if (aContains !== bContains) {
+            return aContains - bContains;
+        }
+        const distanceDiff = levenshteinDistance(raw, a) - levenshteinDistance(raw, b);
+        if (distanceDiff !== 0) {
+            return distanceDiff;
+        }
+        return a.localeCompare(b);
+    })
+        .slice(0, 3);
+}
+async function validateDataSourceFilterProperties(ctx, dataSourceId, filter) {
+    if (!filter) {
+        return;
+    }
+    const refs = new Set();
+    collectFilterPropertyRefs(filter, refs);
+    if (refs.size === 0) {
+        return;
+    }
+    const schema = await hydrateDataSourceSchema(ctx, dataSourceId);
+    const validNames = Object.keys(schema);
+    const validIds = new Set(Object.values(schema)
+        .map((entry) => entry.id)
+        .filter((value) => typeof value === "string" && value.length > 0));
+    for (const property of refs) {
+        if (schema[property] || validIds.has(property)) {
+            continue;
+        }
+        const suggestions = suggestPropertyNames(property, validNames);
+        const suggestionText = suggestions.length > 0
+            ? ` Did you mean ${suggestions.map((name) => `"${name}"`).join(", ")}?`
+            : "";
+        throw new CliError("invalid_input", `Unknown filter property "${property}" for this data source.${suggestionText}`);
+    }
+}
 async function withBestEffortPageMutation(ctx, pageId, apply) {
     const attempts = 2;
     for (let attempt = 1; attempt <= attempts; attempt += 1) {
@@ -288,6 +376,7 @@ export async function getDataSourceSchema(notion, dataSourceId) {
     };
 }
 export async function queryDataSourcePages(ctx, input) {
+    await validateDataSourceFilterProperties(ctx, input.dataSourceId, input.filter);
     const payload = {
         data_source_id: input.dataSourceId,
         page_size: Math.min(Math.max(1, input.limit), 100),
@@ -455,6 +544,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 +645,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 +694,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 +1168,32 @@ 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,
+    };
+}
+export async function areBlocksDeleted(notion, blockIds) {
+    for (const blockId of blockIds) {
+        try {
+            const block = asRecord(await notion.retrieveBlock(blockId));
+            if (block.archived !== true) {
+                return false;
+            }
+        }
+        catch (error) {
+            const status = getStatus(error);
+            if (status === 404) {
+                continue;
+            }
+            throw error;
+        }
+    }
+    return true;
+}

package/package.json

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