@gravitykit/block-mcp 2.0.0-beta

package/src/__tests__/tools/posts/create_post.test.ts

@@ -0,0 +1,84 @@
+/**
+ * Tool tests: create_post
+ *
+ * Covers:
+ *   - Schema: title required
+ *   - Validation: non-empty title (empty, whitespace-only)
+ *   - Validation: content + blocks mutually exclusive
+ *   - Happy path: args forwarded to client
+ *   - Response shape passthrough
+ */
+
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { POST_TOOLS, handlePostTool } from '../../../tools/posts.js';
+import { makeMockClient } from '../../helpers/mock-client.js';
+import { createPostResponse } from '../../fixtures/rest-responses.js';
+
+describe('create_post — schema', () => {
+  it('exposes create_post tool', () => {
+    expect(POST_TOOLS.map((t) => t.name)).toContain('create_post');
+  });
+
+  it('requires title in inputSchema', () => {
+    const tool = POST_TOOLS.find((t) => t.name === 'create_post')!;
+    expect(tool.inputSchema.required).toContain('title');
+  });
+});
+
+describe('create_post — validation', () => {
+  let client: ReturnType<typeof makeMockClient>;
+  beforeEach(() => { client = makeMockClient(); vi.clearAllMocks(); });
+
+  it('rejects missing title', async () => {
+    await expect(handlePostTool('create_post', {}, client as any)).rejects.toThrow('title');
+    expect(client.createPost).not.toHaveBeenCalled();
+  });
+
+  it('rejects empty-string title', async () => {
+    await expect(handlePostTool('create_post', { title: '' }, client as any)).rejects.toThrow('title');
+    expect(client.createPost).not.toHaveBeenCalled();
+  });
+
+  it('rejects whitespace-only title', async () => {
+    await expect(handlePostTool('create_post', { title: '   ' }, client as any)).rejects.toThrow('title');
+    expect(client.createPost).not.toHaveBeenCalled();
+  });
+
+  it('rejects content and blocks together (mutually exclusive)', async () => {
+    await expect(handlePostTool('create_post', {
+      title: 'X', content: 'some text', blocks: [{ name: 'core/paragraph' }],
+    }, client as any)).rejects.toThrow('mutually exclusive');
+    expect(client.createPost).not.toHaveBeenCalled();
+  });
+});
+
+describe('create_post — happy path', () => {
+  let client: ReturnType<typeof makeMockClient>;
+  beforeEach(() => {
+    client = makeMockClient();
+    client.createPost.mockResolvedValue(createPostResponse);
+    vi.clearAllMocks();
+  });
+
+  it('forwards args to client', async () => {
+    await handlePostTool('create_post', {
+      title: 'Hello', status: 'draft', categories: [12],
+    }, client as any);
+    expect(client.createPost).toHaveBeenCalledWith({
+      title: 'Hello', status: 'draft', categories: [12],
+    });
+  });
+
+  it('returns client response unchanged', async () => {
+    const result = await handlePostTool('create_post', { title: 'X' }, client as any);
+    expect(result).toEqual(createPostResponse);
+  });
+
+  it('response includes success, id, post_type, status', async () => {
+    const result = await handlePostTool('create_post', { title: 'X' }, client as any) as any;
+    expect(result.success).toBe(true);
+    expect(result.id).toBe(9999);
+    expect(result.post_type).toBe('post');
+    expect(result.status).toBe('draft');
+  });
+});

package/src/__tests__/tools/posts/update_post.test.ts

@@ -0,0 +1,93 @@
+/**
+ * Tool tests: update_post
+ *
+ * Covers:
+ *   - Schema: post_id required
+ *   - Validation: post_id required
+ *   - Validation: at least one mutating field besides post_id
+ *   - Request shape: separates post_id from body
+ *   - Response shape passthrough
+ *   - Unknown tool throws
+ */
+
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { POST_TOOLS, handlePostTool } from '../../../tools/posts.js';
+import { makeMockClient } from '../../helpers/mock-client.js';
+import { updatePostResponse } from '../../fixtures/rest-responses.js';
+
+describe('update_post — schema', () => {
+  it('exposes update_post tool', () => {
+    expect(POST_TOOLS.map((t) => t.name)).toContain('update_post');
+  });
+
+  it('requires post_id in inputSchema', () => {
+    const tool = POST_TOOLS.find((t) => t.name === 'update_post')!;
+    expect(tool.inputSchema.required).toContain('post_id');
+  });
+});
+
+describe('update_post — validation', () => {
+  let client: ReturnType<typeof makeMockClient>;
+  beforeEach(() => { client = makeMockClient(); vi.clearAllMocks(); });
+
+  it('requires post_id', async () => {
+    await expect(handlePostTool('update_post', { title: 'X' }, client as any))
+      .rejects.toThrow('post_id');
+    expect(client.updatePost).not.toHaveBeenCalled();
+  });
+
+  it('requires at least one mutating field besides post_id', async () => {
+    await expect(handlePostTool('update_post', { post_id: 1 }, client as any))
+      .rejects.toThrow('at least one mutating field');
+    expect(client.updatePost).not.toHaveBeenCalled();
+  });
+});
+
+describe('update_post — request shape', () => {
+  let client: ReturnType<typeof makeMockClient>;
+  beforeEach(() => {
+    client = makeMockClient();
+    client.updatePost.mockResolvedValue(updatePostResponse);
+    vi.clearAllMocks();
+  });
+
+  it('separates post_id from body and forwards remaining fields', async () => {
+    await handlePostTool('update_post', { post_id: 99, status: 'publish', title: 'New' }, client as any);
+    expect(client.updatePost).toHaveBeenCalledWith(99, { status: 'publish', title: 'New' });
+  });
+
+  it('post_id is not included in the body', async () => {
+    await handlePostTool('update_post', { post_id: 5, status: 'draft' }, client as any);
+    const body = client.updatePost.mock.calls[0]![1] as Record<string, unknown>;
+    expect(body).not.toHaveProperty('post_id');
+  });
+});
+
+describe('update_post — response shape', () => {
+  let client: ReturnType<typeof makeMockClient>;
+  beforeEach(() => {
+    client = makeMockClient();
+    client.updatePost.mockResolvedValue(updatePostResponse);
+    vi.clearAllMocks();
+  });
+
+  it('returns client response unchanged', async () => {
+    const result = await handlePostTool('update_post', { post_id: 1, status: 'publish' }, client as any);
+    expect(result).toEqual(updatePostResponse);
+  });
+
+  it('response includes transitioned_to_publish', async () => {
+    const result = await handlePostTool('update_post', { post_id: 1, status: 'publish' }, client as any) as any;
+    expect(result.transitioned_to_publish).toBe(true);
+  });
+});
+
+describe('update_post — unknown tool', () => {
+  let client: ReturnType<typeof makeMockClient>;
+  beforeEach(() => { client = makeMockClient(); });
+
+  it('throws on unknown tool name', async () => {
+    await expect(handlePostTool('unknown_tool', { post_id: 1 }, client as any))
+      .rejects.toThrow('Unknown post tool');
+  });
+});

package/src/__tests__/tools/read/get_block.test.ts

@@ -0,0 +1,96 @@
+/**
+ * Tool tests: get_block
+ *
+ * Covers:
+ *   - Required: post_id
+ *   - XOR: exactly one of ref or flat_index
+ *   - Routing: ref → client.getBlock(postId, {ref})
+ *   - Routing: flat_index → client.getBlock(postId, {flatIndex})
+ *   - flat_index:0 is valid (Number.isFinite check, not truthy)
+ *   - Response shape: { success, saved } via assertSavedBlock
+ *   - Empty string ref treated as missing (XOR with flat_index)
+ *   - Non-finite flat_index (NaN/Infinity) treated as missing
+ */
+
+import { describe, it, expect, beforeEach } from 'vitest';
+import { handleReadTool } from '../../../tools/read.js';
+import { makeMockClient } from '../../helpers/mock-client.js';
+import { getBlockResponse } from '../../fixtures/rest-responses.js';
+import { assertSavedBlock } from '../../helpers/schema-asserts.js';
+
+describe('get_block — input validation', () => {
+  let client: ReturnType<typeof makeMockClient>;
+  beforeEach(() => {
+    client = makeMockClient();
+    client.getBlock.mockResolvedValue(getBlockResponse);
+  });
+
+  it('requires post_id', async () => {
+    await expect(
+      handleReadTool('get_block', { ref: 'blk_a' }, client as any)
+    ).rejects.toThrow(/post_id is required/);
+  });
+
+  it('requires exactly one of ref or flat_index (rejects neither)', async () => {
+    await expect(
+      handleReadTool('get_block', { post_id: 1 }, client as any)
+    ).rejects.toThrow(/exactly one of ref or flat_index/);
+  });
+
+  it('rejects both ref and flat_index together', async () => {
+    await expect(
+      handleReadTool('get_block', { post_id: 1, ref: 'blk_a', flat_index: 0 }, client as any)
+    ).rejects.toThrow(/exactly one of ref or flat_index/);
+  });
+
+  it('treats empty-string ref as missing (still requires flat_index)', async () => {
+    await expect(
+      handleReadTool('get_block', { post_id: 1, ref: '' }, client as any)
+    ).rejects.toThrow(/exactly one of ref or flat_index/);
+  });
+
+  it('treats NaN flat_index as missing (still requires ref)', async () => {
+    await expect(
+      handleReadTool('get_block', { post_id: 1, flat_index: NaN }, client as any)
+    ).rejects.toThrow(/exactly one of ref or flat_index/);
+  });
+});
+
+describe('get_block — routing', () => {
+  let client: ReturnType<typeof makeMockClient>;
+  beforeEach(() => {
+    client = makeMockClient();
+    client.getBlock.mockResolvedValue(getBlockResponse);
+  });
+
+  it('forwards ref to client.getBlock', async () => {
+    await handleReadTool('get_block', { post_id: 42, ref: 'blk_a' }, client as any);
+    expect(client.getBlock).toHaveBeenCalledWith(42, { ref: 'blk_a' });
+  });
+
+  it('forwards flat_index to client.getBlock as flatIndex (camelCase)', async () => {
+    await handleReadTool('get_block', { post_id: 42, flat_index: 3 }, client as any);
+    expect(client.getBlock).toHaveBeenCalledWith(42, { flatIndex: 3 });
+  });
+
+  it('flat_index:0 is a valid lookup (not falsy-rejected)', async () => {
+    await handleReadTool('get_block', { post_id: 1, flat_index: 0 }, client as any);
+    expect(client.getBlock).toHaveBeenCalledWith(1, { flatIndex: 0 });
+  });
+});
+
+describe('get_block — response shape', () => {
+  let client: ReturnType<typeof makeMockClient>;
+  beforeEach(() => {
+    client = makeMockClient();
+    client.getBlock.mockResolvedValue(getBlockResponse);
+  });
+
+  it('returns { success, saved } with a valid saved block', async () => {
+    const result = await handleReadTool('get_block', { post_id: 1, ref: 'blk_a' }, client as any) as {
+      success: boolean; saved: unknown;
+    };
+    expect(result.success).toBe(true);
+    assertSavedBlock(result.saved);
+  });
+});

package/src/__tests__/tools/read/get_page_blocks.test.ts

@@ -0,0 +1,184 @@
+/**
+ * Tool tests: get_page_blocks
+ *
+ * Covers:
+ *   - Input requirement: either post_id or url
+ *   - URL resolution path (when only url is provided)
+ *   - Direct post_id path (skips resolveUrl)
+ *   - All query-mode flag forwarding (fields, render, search, block_name,
+ *     outline, summary_only, include_legacy_paths, persist_refs)
+ *   - summary_only short-circuits enrichment
+ *   - Response shape: post_id + summary + blocks + block_count + warnings
+ *   - Enrichment adds preference warnings for legacy/avoid blocks
+ *   - persist_refs only forwarded when provided (omitted otherwise)
+ */
+
+import { describe, it, expect, beforeEach } from 'vitest';
+import { handleReadTool } from '../../../tools/read.js';
+import { makeMockClient } from '../../helpers/mock-client.js';
+import { pageBlocksResponse, resolveUrlResponse } from '../../fixtures/rest-responses.js';
+import { mixedPageBlocks, legacyPageBlocks } from '../../fixtures/block-trees.js';
+
+describe('get_page_blocks — input validation', () => {
+  let client: ReturnType<typeof makeMockClient>;
+  beforeEach(() => {
+    client = makeMockClient();
+    client.getPageBlocks.mockResolvedValue(pageBlocksResponse);
+  });
+
+  it('throws when neither post_id nor url is supplied', async () => {
+    await expect(
+      handleReadTool('get_page_blocks', {}, client as any)
+    ).rejects.toThrow(/post_id or url/);
+  });
+
+  it('accepts post_id alone', async () => {
+    await expect(
+      handleReadTool('get_page_blocks', { post_id: 42 }, client as any)
+    ).resolves.toBeDefined();
+  });
+
+  it('accepts url alone', async () => {
+    client.resolveUrl.mockResolvedValueOnce(resolveUrlResponse);
+    await expect(
+      handleReadTool('get_page_blocks', { url: '/path/' }, client as any)
+    ).resolves.toBeDefined();
+  });
+});
+
+describe('get_page_blocks — URL resolution', () => {
+  let client: ReturnType<typeof makeMockClient>;
+  beforeEach(() => {
+    client = makeMockClient();
+    client.getPageBlocks.mockResolvedValue(pageBlocksResponse);
+  });
+
+  it('resolves url to post_id via client.resolveUrl', async () => {
+    client.resolveUrl.mockResolvedValueOnce({ ...resolveUrlResponse, post_id: 555 });
+    await handleReadTool('get_page_blocks', { url: '/some/path/' }, client as any);
+    expect(client.resolveUrl).toHaveBeenCalledWith('/some/path/');
+    expect(client.getPageBlocks).toHaveBeenCalledWith(555, expect.any(Object));
+  });
+
+  it('skips resolveUrl when post_id is provided', async () => {
+    await handleReadTool('get_page_blocks', { post_id: 99 }, client as any);
+    expect(client.resolveUrl).not.toHaveBeenCalled();
+    expect(client.getPageBlocks).toHaveBeenCalledWith(99, expect.any(Object));
+  });
+
+  it('returns the resolved post_id in the response (url path)', async () => {
+    client.resolveUrl.mockResolvedValueOnce({ ...resolveUrlResponse, post_id: 1234 });
+    const result = await handleReadTool('get_page_blocks', { url: '/x' }, client as any);
+    expect((result as { post_id: number }).post_id).toBe(1234);
+  });
+});
+
+describe('get_page_blocks — option forwarding', () => {
+  let client: ReturnType<typeof makeMockClient>;
+  beforeEach(() => {
+    client = makeMockClient();
+    client.getPageBlocks.mockResolvedValue(pageBlocksResponse);
+  });
+
+  it('forwards fields, render, search, block_name, outline, summary_only, include_legacy_paths', async () => {
+    await handleReadTool('get_page_blocks', {
+      post_id: 1,
+      fields: 'path,name', render: true, search: 'foo', block_name: 'core/heading',
+      outline: true, include_legacy_paths: true,
+    }, client as any);
+    expect(client.getPageBlocks).toHaveBeenCalledWith(1, expect.objectContaining({
+      fields: 'path,name', render: true, search: 'foo',
+      block_name: 'core/heading', outline: true, include_legacy_paths: true,
+    }));
+  });
+
+  it('omits persist_refs when not provided', async () => {
+    await handleReadTool('get_page_blocks', { post_id: 1 }, client as any);
+    const opts = client.getPageBlocks.mock.calls[0]![1] as Record<string, unknown>;
+    expect('persist_refs' in opts).toBe(false);
+  });
+
+  it('forwards persist_refs:false when explicitly set', async () => {
+    await handleReadTool('get_page_blocks', { post_id: 1, persist_refs: false }, client as any);
+    expect(client.getPageBlocks).toHaveBeenCalledWith(1, expect.objectContaining({ persist_refs: false }));
+  });
+
+  it('forwards persist_refs:true when explicitly set', async () => {
+    await handleReadTool('get_page_blocks', { post_id: 1, persist_refs: true }, client as any);
+    expect(client.getPageBlocks).toHaveBeenCalledWith(1, expect.objectContaining({ persist_refs: true }));
+  });
+});
+
+describe('get_page_blocks — summary_only short-circuit', () => {
+  let client: ReturnType<typeof makeMockClient>;
+  beforeEach(() => {
+    client = makeMockClient();
+    client.getPageBlocks.mockResolvedValue(pageBlocksResponse);
+  });
+
+  it('returns only post_id + summary when summary_only:true', async () => {
+    const result = await handleReadTool(
+      'get_page_blocks',
+      { post_id: 1, summary_only: true },
+      client as any
+    ) as Record<string, unknown>;
+    expect(Object.keys(result).sort()).toEqual(['post_id', 'summary']);
+    expect(result.post_id).toBe(1);
+    expect(result.summary).toBeDefined();
+  });
+
+  it('does not include blocks/warnings keys in summary_only mode', async () => {
+    const result = await handleReadTool(
+      'get_page_blocks', { post_id: 1, summary_only: true }, client as any
+    ) as Record<string, unknown>;
+    expect('blocks' in result).toBe(false);
+    expect('warnings' in result).toBe(false);
+    expect('block_count' in result).toBe(false);
+  });
+});
+
+describe('get_page_blocks — response shape (default mode)', () => {
+  let client: ReturnType<typeof makeMockClient>;
+  beforeEach(() => {
+    client = makeMockClient();
+    client.getPageBlocks.mockResolvedValue(pageBlocksResponse);
+  });
+
+  it('returns post_id, summary, blocks, block_count, warnings', async () => {
+    const result = await handleReadTool('get_page_blocks', { post_id: 7 }, client as any) as Record<string, unknown>;
+    expect(result.post_id).toBe(7);
+    expect(result.summary).toBeDefined();
+    expect(Array.isArray(result.blocks)).toBe(true);
+    expect(typeof result.block_count).toBe('number');
+    expect(Array.isArray(result.warnings)).toBe(true);
+  });
+
+  it('block_count matches blocks.length', async () => {
+    const result = await handleReadTool('get_page_blocks', { post_id: 1 }, client as any) as Record<string, unknown>;
+    expect(result.block_count).toBe((result.blocks as unknown[]).length);
+  });
+
+  it('warnings is empty when content has no legacy/avoid blocks', async () => {
+    client.getPageBlocks.mockResolvedValueOnce({ ...pageBlocksResponse, blocks: mixedPageBlocks });
+    const result = await handleReadTool('get_page_blocks', { post_id: 1 }, client as any) as { warnings: unknown[] };
+    expect(result.warnings).toEqual([]);
+  });
+
+  it('handles missing blocks array (treats as empty)', async () => {
+    client.getPageBlocks.mockResolvedValueOnce({ summary: pageBlocksResponse.summary } as any);
+    const result = await handleReadTool('get_page_blocks', { post_id: 1 }, client as any) as Record<string, unknown>;
+    expect(result.blocks).toEqual([]);
+    expect(result.block_count).toBe(0);
+  });
+});
+
+describe('get_page_blocks — enrichment with legacy blocks', () => {
+  let client: ReturnType<typeof makeMockClient>;
+  beforeEach(() => { client = makeMockClient(); });
+
+  it('produces warnings for legacy ugb/* blocks', async () => {
+    client.getPageBlocks.mockResolvedValueOnce({ blocks: legacyPageBlocks, summary: {} });
+    const result = await handleReadTool('get_page_blocks', { post_id: 1 }, client as any) as { warnings: unknown[] };
+    expect(result.warnings.length).toBeGreaterThan(0);
+  });
+});

package/src/__tests__/tools/read/persist_refs.test.ts

@@ -0,0 +1,35 @@
+/**
+ * Tool tests: get_page_blocks — persist_refs option
+ *
+ * Covers:
+ *   - persist_refs not forwarded when not specified (server default applies)
+ *   - persist_refs:false forwarded when explicitly set
+ *   - persist_refs:true forwarded when explicitly set
+ */
+
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { handleReadTool } from '../../../tools/read.js';
+import { makeMockClient } from '../../helpers/mock-client.js';
+
+describe('get_page_blocks — persist_refs option', () => {
+  let client: ReturnType<typeof makeMockClient>;
+  beforeEach(() => { client = makeMockClient(); vi.clearAllMocks(); });
+
+  it('does not pass persist_refs when not specified (server default applies)', async () => {
+    await handleReadTool('get_page_blocks', { post_id: 1 }, client as any);
+    const opts = client.getPageBlocks.mock.calls[0]![1] as Record<string, unknown>;
+    expect(opts).not.toHaveProperty('persist_refs');
+  });
+
+  it('forwards persist_refs:false when explicitly set', async () => {
+    await handleReadTool('get_page_blocks', { post_id: 1, persist_refs: false }, client as any);
+    const opts = client.getPageBlocks.mock.calls[0]![1] as Record<string, unknown>;
+    expect(opts.persist_refs).toBe(false);
+  });
+
+  it('forwards persist_refs:true when explicitly set', async () => {
+    await handleReadTool('get_page_blocks', { post_id: 1, persist_refs: true }, client as any);
+    const opts = client.getPageBlocks.mock.calls[0]![1] as Record<string, unknown>;
+    expect(opts.persist_refs).toBe(true);
+  });
+});

package/src/__tests__/tools/terms/list_terms.test.ts

@@ -0,0 +1,91 @@
+/**
+ * Tool tests: list_terms
+ *
+ * Covers:
+ *   - Schema: list_terms exposed
+ *   - Empty args: passes through (taxonomy default server-side)
+ *   - Filter forwarding: taxonomy, search, per_page, page
+ *   - Response shape: taxonomy, total, page, per_page, terms
+ *   - Unknown tool throws
+ */
+
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { TERM_TOOLS, handleTermTool } from '../../../tools/terms.js';
+import { makeMockClient } from '../../helpers/mock-client.js';
+
+describe('list_terms — schema', () => {
+  it('exposes list_terms tool', () => {
+    expect(TERM_TOOLS.map((t) => t.name)).toContain('list_terms');
+  });
+});
+
+describe('list_terms — request shape', () => {
+  let client: ReturnType<typeof makeMockClient>;
+  beforeEach(() => { client = makeMockClient(); vi.clearAllMocks(); });
+
+  it('passes empty args to client (server applies default taxonomy)', async () => {
+    await handleTermTool('list_terms', {}, client as any);
+    expect(client.listTerms).toHaveBeenCalledWith({});
+  });
+
+  it('forwards taxonomy filter', async () => {
+    await handleTermTool('list_terms', { taxonomy: 'post_tag' }, client as any);
+    expect(client.listTerms).toHaveBeenCalledWith(expect.objectContaining({ taxonomy: 'post_tag' }));
+  });
+
+  it('forwards search filter', async () => {
+    await handleTermTool('list_terms', { taxonomy: 'category', search: 'wp' }, client as any);
+    expect(client.listTerms).toHaveBeenCalledWith(expect.objectContaining({ search: 'wp' }));
+  });
+
+  it('forwards per_page and page', async () => {
+    await handleTermTool('list_terms', { taxonomy: 'post_tag', per_page: 25, page: 2 }, client as any);
+    expect(client.listTerms).toHaveBeenCalledWith({
+      taxonomy: 'post_tag', per_page: 25, page: 2,
+    });
+  });
+
+  it('forwards all filters together', async () => {
+    await handleTermTool('list_terms', {
+      taxonomy: 'category', search: 'news', per_page: 50, page: 3,
+    }, client as any);
+    expect(client.listTerms).toHaveBeenCalledWith({
+      taxonomy: 'category', search: 'news', per_page: 50, page: 3,
+    });
+  });
+});
+
+describe('list_terms — response shape', () => {
+  let client: ReturnType<typeof makeMockClient>;
+  beforeEach(() => {
+    client = makeMockClient();
+    vi.clearAllMocks();
+  });
+
+  it('returns taxonomy, total, page, per_page, terms', async () => {
+    client.listTerms.mockResolvedValue({
+      taxonomy: 'category', total: 5, page: 1, per_page: 100,
+      terms: [{ id: 1, name: 'Uncategorized', slug: 'uncategorized', count: 10 }],
+    });
+    const result = await handleTermTool('list_terms', {}, client as any) as any;
+    expect(result.taxonomy).toBe('category');
+    expect(result.total).toBe(5);
+    expect(result.terms).toHaveLength(1);
+  });
+
+  it('handles empty terms array', async () => {
+    const result = await handleTermTool('list_terms', {}, client as any) as any;
+    expect(result.terms).toEqual([]);
+    expect(result.total).toBe(0);
+  });
+});
+
+describe('list_terms — unknown tool', () => {
+  let client: ReturnType<typeof makeMockClient>;
+  beforeEach(() => { client = makeMockClient(); });
+
+  it('throws on unknown tool name', async () => {
+    await expect(handleTermTool('unknown_tool', {}, client as any))
+      .rejects.toThrow('Unknown term tool');
+  });
+});

package/src/__tests__/tools/write/delete_block.test.ts

@@ -0,0 +1,91 @@
+/**
+ * Tool tests: delete_block
+ *
+ * Covers:
+ *   - Input validation (post_id, top_level_counter/ref XOR, count bounds)
+ *   - Index path → client.deleteBlock
+ *   - Ref path → client.deleteBlockByRef
+ *   - count forwarding
+ *   - Edge cases: counter=0, count=1
+ */
+
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { handleWriteTool } from '../../../tools/write.js';
+import { makeMockClient } from '../../helpers/mock-client.js';
+
+describe('delete_block — validation', () => {
+  let client: ReturnType<typeof makeMockClient>;
+  beforeEach(() => { client = makeMockClient(); vi.clearAllMocks(); });
+
+  it('requires post_id', async () => {
+    await expect(
+      handleWriteTool('delete_block', { top_level_counter: 0 }, client as any)
+    ).rejects.toThrow('post_id');
+  });
+
+  it('requires top_level_counter OR ref (not neither)', async () => {
+    await expect(
+      handleWriteTool('delete_block', { post_id: 1 }, client as any)
+    ).rejects.toThrow(/Provide either top_level_counter/);
+  });
+
+  it('rejects when both top_level_counter and ref provided', async () => {
+    await expect(
+      handleWriteTool('delete_block', { post_id: 1, top_level_counter: 0, ref: 'blk_x' }, client as any)
+    ).rejects.toThrow(/top_level_counter OR ref, not both/);
+  });
+
+  it('rejects NaN top_level_counter', async () => {
+    await expect(
+      handleWriteTool('delete_block', { post_id: 1, top_level_counter: NaN }, client as any)
+    ).rejects.toThrow(/Provide either top_level_counter/);
+  });
+
+  it('rejects count=0 (must be positive)', async () => {
+    await expect(
+      handleWriteTool('delete_block', { post_id: 1, top_level_counter: 0, count: 0 }, client as any)
+    ).rejects.toThrow(/count must be a positive integer/);
+  });
+});
+
+describe('delete_block — index path', () => {
+  let client: ReturnType<typeof makeMockClient>;
+  beforeEach(() => { client = makeMockClient(); vi.clearAllMocks(); });
+
+  it('routes to deleteBlock (not deleteBlockByRef)', async () => {
+    await handleWriteTool('delete_block', { post_id: 1, top_level_counter: 3 }, client as any);
+    expect(client.deleteBlock).toHaveBeenCalledWith(1, 3, undefined);
+    expect(client.deleteBlockByRef).not.toHaveBeenCalled();
+  });
+
+  it('top_level_counter=0 is a valid target', async () => {
+    await handleWriteTool('delete_block', { post_id: 1, top_level_counter: 0 }, client as any);
+    expect(client.deleteBlock).toHaveBeenCalledWith(1, 0, undefined);
+  });
+
+  it('forwards count to deleteBlock', async () => {
+    await handleWriteTool('delete_block', { post_id: 1, top_level_counter: 2, count: 3 }, client as any);
+    expect(client.deleteBlock).toHaveBeenCalledWith(1, 2, 3);
+  });
+
+  it('count=1 is accepted', async () => {
+    await handleWriteTool('delete_block', { post_id: 1, top_level_counter: 0, count: 1 }, client as any);
+    expect(client.deleteBlock).toHaveBeenCalledWith(1, 0, 1);
+  });
+});
+
+describe('delete_block — ref path', () => {
+  let client: ReturnType<typeof makeMockClient>;
+  beforeEach(() => { client = makeMockClient(); vi.clearAllMocks(); });
+
+  it('routes to deleteBlockByRef (not deleteBlock)', async () => {
+    await handleWriteTool('delete_block', { post_id: 1, ref: 'blk_target' }, client as any);
+    expect(client.deleteBlockByRef).toHaveBeenCalledWith(1, 'blk_target', undefined);
+    expect(client.deleteBlock).not.toHaveBeenCalled();
+  });
+
+  it('forwards count through ref path', async () => {
+    await handleWriteTool('delete_block', { post_id: 1, ref: 'blk_x', count: 3 }, client as any);
+    expect(client.deleteBlockByRef).toHaveBeenCalledWith(1, 'blk_x', 3);
+  });
+});