@gravitykit/block-mcp 2.0.0-beta

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

@@ -0,0 +1,149 @@
+/**
+ * Tool tests: insert_blocks
+ *
+ * Covers:
+ *   - Input validation
+ *   - Positioning params (after/before/after_ref/before_ref)
+ *   - Enricher wiring
+ *   - Warning enrichment (formatted_warnings)
+ *   - Clean path (no warnings)
+ *   - Ref in inserted blocks forwarded
+ */
+
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { handleWriteTool } from '../../../tools/write.js';
+import { makeMockClient } from '../../helpers/mock-client.js';
+import { assertHasFormattedWarning, assertNoFormattedWarnings } from '../../helpers/request-matchers.js';
+
+vi.mock('../../../enrichers.js', () => ({
+  enrichBlock: vi.fn(async (block: any) => block),
+  enrichBlocks: vi.fn(async (blocks: any[]) =>
+    blocks.map((b: any) => ({ ...b, attributes: { ...b.attributes, enriched: true } }))
+  ),
+}));
+
+describe('insert_blocks — validation', () => {
+  let client: ReturnType<typeof makeMockClient>;
+  beforeEach(() => { client = makeMockClient(); vi.clearAllMocks(); });
+
+  it('requires post_id', async () => {
+    await expect(
+      handleWriteTool('insert_blocks', { blocks: [{ name: 'core/paragraph' }] }, client as any)
+    ).rejects.toThrow('post_id');
+  });
+
+  it('requires at least one block', async () => {
+    await expect(
+      handleWriteTool('insert_blocks', { post_id: 1 }, client as any)
+    ).rejects.toThrow('block');
+  });
+
+  it('rejects empty blocks array', async () => {
+    await expect(
+      handleWriteTool('insert_blocks', { post_id: 1, blocks: [] }, client as any)
+    ).rejects.toThrow('block');
+  });
+});
+
+describe('insert_blocks — positioning', () => {
+  let client: ReturnType<typeof makeMockClient>;
+  beforeEach(() => { client = makeMockClient(); vi.clearAllMocks(); });
+
+  it('forwards after_top_level as "after" to client', async () => {
+    await handleWriteTool('insert_blocks', {
+      post_id: 1, after_top_level: 5, blocks: [{ name: 'core/paragraph' }],
+    }, client as any);
+    expect(client.insertBlocks).toHaveBeenCalledWith(1, expect.objectContaining({ after: 5 }));
+  });
+
+  it('forwards before_top_level as "before" to client', async () => {
+    await handleWriteTool('insert_blocks', {
+      post_id: 1, before_top_level: 2, blocks: [{ name: 'core/paragraph' }],
+    }, client as any);
+    expect(client.insertBlocks).toHaveBeenCalledWith(1, expect.objectContaining({ before: 2 }));
+  });
+
+  it('forwards after_ref to client body', async () => {
+    await handleWriteTool('insert_blocks', {
+      post_id: 1, after_ref: 'blk_anchor', blocks: [{ name: 'core/paragraph', innerHTML: '<p>x</p>' }],
+    }, client as any);
+    const callArg = client.insertBlocks.mock.calls[0][1] as any;
+    expect(callArg.after_ref).toBe('blk_anchor');
+  });
+
+  it('forwards before_ref to client body', async () => {
+    await handleWriteTool('insert_blocks', {
+      post_id: 1, before_ref: 'blk_anchor2', blocks: [{ name: 'core/paragraph', innerHTML: '<p>x</p>' }],
+    }, client as any);
+    const callArg = client.insertBlocks.mock.calls[0][1] as any;
+    expect(callArg.before_ref).toBe('blk_anchor2');
+  });
+
+  it('does not include after_ref/before_ref keys when not provided', async () => {
+    await handleWriteTool('insert_blocks', {
+      post_id: 1, after_top_level: 2, blocks: [{ name: 'core/paragraph', innerHTML: '<p>x</p>' }],
+    }, client as any);
+    const callArg = client.insertBlocks.mock.calls[0][1] as any;
+    expect(callArg).not.toHaveProperty('after_ref');
+    expect(callArg).not.toHaveProperty('before_ref');
+  });
+});
+
+describe('insert_blocks — enricher wiring', () => {
+  let client: ReturnType<typeof makeMockClient>;
+  beforeEach(() => { client = makeMockClient(); vi.clearAllMocks(); });
+
+  it('passes blocks through enrichBlocks', async () => {
+    const { enrichBlocks } = await import('../../../enrichers.js');
+    (enrichBlocks as ReturnType<typeof vi.fn>).mockClear();
+    await handleWriteTool('insert_blocks', {
+      post_id: 1, blocks: [{ name: 'core/paragraph', attributes: { content: 'Hi' } }],
+    }, client as any);
+    expect(enrichBlocks).toHaveBeenCalled();
+  });
+
+  it('enriched attributes reach the client', async () => {
+    await handleWriteTool('insert_blocks', {
+      post_id: 1, blocks: [{ name: 'core/paragraph', attributes: { content: 'Hi' } }],
+    }, client as any);
+    const callArg = client.insertBlocks.mock.calls[0][1] as any;
+    expect(callArg.blocks[0].attributes).toMatchObject({ content: 'Hi', enriched: true });
+  });
+});
+
+describe('insert_blocks — warning enrichment', () => {
+  let client: ReturnType<typeof makeMockClient>;
+  beforeEach(() => { client = makeMockClient(); vi.clearAllMocks(); });
+
+  it('adds formatted_warnings when response has warnings', async () => {
+    client.insertBlocks.mockResolvedValueOnce({
+      success: true, inserted: [], before_revision_id: 1, revision_id: 2,
+      warnings: [{ block: 'oldns/heading', message: 'AVOID', suggested_replacement: 'core/heading' }],
+    });
+    const result = await handleWriteTool('insert_blocks', {
+      post_id: 1, blocks: [{ name: 'oldns/heading' }],
+    }, client as any);
+    assertHasFormattedWarning(result, 'WARNING');
+    assertHasFormattedWarning(result, 'oldns/heading');
+  });
+
+  it('no formatted_warnings when response has none', async () => {
+    const result = await handleWriteTool('insert_blocks', {
+      post_id: 1, blocks: [{ name: 'core/heading' }],
+    }, client as any);
+    assertNoFormattedWarnings(result);
+    expect((result as any).success).toBe(true);
+  });
+
+  it('returns ref on inserted blocks', async () => {
+    client.insertBlocks.mockResolvedValueOnce({
+      success: true,
+      inserted: [{ index: 0, name: 'core/paragraph', ref: 'blk_new001' }],
+      warnings: [], before_revision_id: 1, revision_id: 2,
+    });
+    const result = await handleWriteTool('insert_blocks', {
+      post_id: 1, blocks: [{ name: 'core/paragraph' }],
+    }, client as any) as any;
+    expect(result.inserted[0].ref).toBe('blk_new001');
+  });
+});

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

@@ -0,0 +1,177 @@
+/**
+ * Tool tests: ref-based addressing for write tools
+ *
+ * Covers:
+ *   - update_block: flat_index path vs ref path (XOR validation + routing)
+ *   - delete_block: top_level_counter vs ref (XOR validation + routing)
+ *   - insert_blocks: after_ref / before_ref forwarded to client
+ *   - NaN / negative integer guards for flat_index and top_level_counter
+ */
+
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { handleWriteTool } from '../../../tools/write.js';
+import { makeMockClient } from '../../helpers/mock-client.js';
+
+vi.mock('../../../enrichers.js', () => ({
+  enrichBlock: vi.fn(async (block: any) => block),
+  enrichBlocks: vi.fn(async (blocks: any[]) => blocks),
+}));
+
+describe('update_block — ref vs flat_index routing', () => {
+  let client: ReturnType<typeof makeMockClient>;
+  beforeEach(() => { client = makeMockClient(); vi.clearAllMocks(); });
+
+  it('routes to updateBlock when only flat_index is provided', async () => {
+    await handleWriteTool('update_block', { post_id: 1, flat_index: 5, attributes: { level: 3 } }, client as any);
+    expect(client.updateBlock).toHaveBeenCalledWith(1, 5, { attributes: { level: 3 }, innerHTML: undefined });
+    expect(client.updateBlockByRef).not.toHaveBeenCalled();
+  });
+
+  it('routes to updateBlockByRef when only ref is provided', async () => {
+    await handleWriteTool('update_block', { post_id: 1, ref: 'blk_abc12345', attributes: { level: 3 } }, client as any);
+    expect(client.updateBlockByRef).toHaveBeenCalledWith(1, 'blk_abc12345', { attributes: { level: 3 }, innerHTML: undefined });
+    expect(client.updateBlock).not.toHaveBeenCalled();
+  });
+
+  it('rejects when both flat_index and ref are provided', async () => {
+    await expect(
+      handleWriteTool('update_block', { post_id: 1, flat_index: 0, ref: 'blk_abc', attributes: {} }, client as any)
+    ).rejects.toThrow(/flat_index OR ref, not both/);
+  });
+
+  it('rejects when neither flat_index nor ref is provided', async () => {
+    await expect(
+      handleWriteTool('update_block', { post_id: 1, attributes: {} }, client as any)
+    ).rejects.toThrow(/Provide either flat_index/);
+  });
+
+  it('rejects empty-string ref', async () => {
+    await expect(
+      handleWriteTool('update_block', { post_id: 1, ref: '', attributes: {} }, client as any)
+    ).rejects.toThrow(/Provide either flat_index/);
+  });
+
+  it('passes innerHTML through ref path', async () => {
+    await handleWriteTool('update_block', { post_id: 1, ref: 'blk_x', innerHTML: '<h2>hi</h2>' }, client as any);
+    expect(client.updateBlockByRef).toHaveBeenCalledWith(1, 'blk_x', { attributes: undefined, innerHTML: '<h2>hi</h2>' });
+  });
+});
+
+describe('delete_block — ref vs top_level_counter routing', () => {
+  let client: ReturnType<typeof makeMockClient>;
+  beforeEach(() => { client = makeMockClient(); vi.clearAllMocks(); });
+
+  it('routes to deleteBlock when only top_level_counter is provided', 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('routes to deleteBlockByRef when only ref is provided', 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('rejects when both top_level_counter and ref are 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 when neither targeting field is provided', async () => {
+    await expect(
+      handleWriteTool('delete_block', { post_id: 1 }, client as any)
+    ).rejects.toThrow(/Provide either top_level_counter/);
+  });
+
+  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 parameter 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);
+  });
+});
+
+describe('insert_blocks — after_ref / before_ref', () => {
+  let client: ReturnType<typeof makeMockClient>;
+  beforeEach(() => { client = makeMockClient(); vi.clearAllMocks(); });
+
+  it('forwards after_ref to client', async () => {
+    await handleWriteTool('insert_blocks', {
+      post_id: 1, after_ref: 'blk_anchor',
+      blocks: [{ name: 'core/paragraph', innerHTML: '<p>x</p>' }],
+    }, client as any);
+    const call = client.insertBlocks.mock.calls[0]![1] as Record<string, unknown>;
+    expect(call.after_ref).toBe('blk_anchor');
+  });
+
+  it('forwards before_ref to client', async () => {
+    await handleWriteTool('insert_blocks', {
+      post_id: 1, before_ref: 'blk_anchor2',
+      blocks: [{ name: 'core/paragraph', innerHTML: '<p>x</p>' }],
+    }, client as any);
+    const call = client.insertBlocks.mock.calls[0]![1] as Record<string, unknown>;
+    expect(call.before_ref).toBe('blk_anchor2');
+  });
+
+  it('does not include after_ref/before_ref when using numeric position', async () => {
+    await handleWriteTool('insert_blocks', {
+      post_id: 1, after_top_level: 2,
+      blocks: [{ name: 'core/paragraph', innerHTML: '<p>x</p>' }],
+    }, client as any);
+    const call = client.insertBlocks.mock.calls[0]![1] as Record<string, unknown>;
+    expect(call).not.toHaveProperty('after_ref');
+    expect(call).not.toHaveProperty('before_ref');
+    expect(call.after).toBe(2);
+  });
+
+  it('response preserves ref on inserted blocks', async () => {
+    client.insertBlocks.mockResolvedValueOnce({
+      success: true,
+      inserted: [{ index: 0, name: 'core/heading', ref: 'blk_new001' }],
+      warnings: [], before_revision_id: 1, revision_id: 2,
+    });
+    const result = await handleWriteTool('insert_blocks', {
+      post_id: 1, blocks: [{ name: 'core/paragraph' }],
+    }, client as any) as any;
+    expect(result.inserted[0].ref).toBe('blk_new001');
+  });
+});
+
+describe('NaN / integer guards', () => {
+  let client: ReturnType<typeof makeMockClient>;
+  beforeEach(() => { client = makeMockClient(); vi.clearAllMocks(); });
+
+  it('update_block rejects NaN flat_index', async () => {
+    await expect(
+      handleWriteTool('update_block', { post_id: 1, flat_index: NaN, attributes: {} }, client as any)
+    ).rejects.toThrow(/Provide either flat_index/);
+  });
+
+  it('update_block rejects negative flat_index', async () => {
+    await expect(
+      handleWriteTool('update_block', { post_id: 1, flat_index: -1, attributes: {} }, client as any)
+    ).rejects.toThrow(/Provide either flat_index/);
+  });
+
+  it('delete_block 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('delete_block 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/);
+  });
+
+  it('delete_block accepts count=1', async () => {
+    await handleWriteTool('delete_block', { post_id: 1, top_level_counter: 0, count: 1 }, client as any);
+    expect(client.deleteBlock).toHaveBeenCalledWith(1, 0, 1);
+  });
+});

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

@@ -0,0 +1,90 @@
+/**
+ * Tool tests: replace_block_range
+ *
+ * Covers:
+ *   - Input validation (post_id, start, count, blocks)
+ *   - Client forwarding
+ *   - Enricher wiring
+ *   - Warning enrichment
+ */
+
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { handleWriteTool } from '../../../tools/write.js';
+import { makeMockClient } from '../../helpers/mock-client.js';
+
+vi.mock('../../../enrichers.js', () => ({
+  enrichBlock: vi.fn(async (block: any) => block),
+  enrichBlocks: vi.fn(async (blocks: any[]) =>
+    blocks.map((b: any) => ({ ...b, attributes: { ...b.attributes, enriched: true } }))
+  ),
+}));
+
+describe('replace_block_range — validation', () => {
+  let client: ReturnType<typeof makeMockClient>;
+  beforeEach(() => { client = makeMockClient(); vi.clearAllMocks(); });
+
+  it('requires post_id', async () => {
+    await expect(
+      handleWriteTool('replace_block_range', { start: 0, count: 1, blocks: [] }, client as any)
+    ).rejects.toThrow('post_id');
+  });
+
+  it('requires start', async () => {
+    await expect(
+      handleWriteTool('replace_block_range', { post_id: 1, count: 1, blocks: [] }, client as any)
+    ).rejects.toThrow('start');
+  });
+
+  it('requires count', async () => {
+    await expect(
+      handleWriteTool('replace_block_range', { post_id: 1, start: 0, blocks: [] }, client as any)
+    ).rejects.toThrow('count');
+  });
+
+  it('requires blocks array', async () => {
+    await expect(
+      handleWriteTool('replace_block_range', { post_id: 1, start: 0, count: 1 }, client as any)
+    ).rejects.toThrow('block');
+  });
+});
+
+describe('replace_block_range — forwarding', () => {
+  let client: ReturnType<typeof makeMockClient>;
+  beforeEach(() => {
+    client = makeMockClient();
+    client.replaceBlocksRange = vi.fn().mockResolvedValue({
+      success: true, removed: 1,
+      inserted: [{ index: 0, name: 'core/paragraph' }],
+      warnings: [],
+      before_revision_id: 1, revision_id: 2,
+    }) as any;
+    vi.clearAllMocks();
+  });
+
+  it('calls replaceBlocksRange with start, count, and blocks', async () => {
+    await handleWriteTool('replace_block_range', {
+      post_id: 1, start: 2, count: 3,
+      blocks: [{ name: 'core/paragraph', attributes: {} }],
+    }, client as any);
+    expect(client.replaceBlocksRange).toHaveBeenCalledWith(1, expect.objectContaining({
+      start: 2, count: 3,
+    }));
+  });
+
+  it('passes blocks through enrichBlocks', async () => {
+    const { enrichBlocks } = await import('../../../enrichers.js');
+    (enrichBlocks as ReturnType<typeof vi.fn>).mockClear();
+    await handleWriteTool('replace_block_range', {
+      post_id: 1, start: 0, count: 1,
+      blocks: [{ name: 'core/paragraph', attributes: {} }],
+    }, client as any);
+    expect(enrichBlocks).toHaveBeenCalled();
+  });
+
+  it('accepts empty blocks array (pure deletion)', async () => {
+    await handleWriteTool('replace_block_range', {
+      post_id: 1, start: 0, count: 2, blocks: [],
+    }, client as any);
+    expect(client.replaceBlocksRange).toHaveBeenCalled();
+  });
+});

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

@@ -0,0 +1,126 @@
+/**
+ * Tool tests: rewrite_post_blocks and revert_to_revision
+ *
+ * rewrite_post_blocks: full page rewrite via replaceAllBlocks
+ * revert_to_revision: revision rollback
+ */
+
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { handleWriteTool } from '../../../tools/write.js';
+import { makeMockClient } from '../../helpers/mock-client.js';
+import { assertHasFormattedWarning, assertNoFormattedWarnings } from '../../helpers/request-matchers.js';
+
+vi.mock('../../../enrichers.js', () => ({
+  enrichBlock: vi.fn(async (block: any) => block),
+  enrichBlocks: vi.fn(async (blocks: any[]) =>
+    blocks.map((b: any) => ({ ...b, attributes: { ...b.attributes, enriched: true } }))
+  ),
+}));
+
+// ── rewrite_post_blocks ───────────────────────────────────────────────────────
+
+describe('rewrite_post_blocks — validation', () => {
+  let client: ReturnType<typeof makeMockClient>;
+  beforeEach(() => { client = makeMockClient(); vi.clearAllMocks(); });
+
+  it('requires post_id', async () => {
+    await expect(
+      handleWriteTool('rewrite_post_blocks', { blocks: [{ name: 'core/paragraph' }] }, client as any)
+    ).rejects.toThrow('post_id');
+  });
+
+  it('requires at least one block', async () => {
+    await expect(
+      handleWriteTool('rewrite_post_blocks', { post_id: 1 }, client as any)
+    ).rejects.toThrow('block');
+  });
+
+  it('rejects empty blocks array', async () => {
+    await expect(
+      handleWriteTool('rewrite_post_blocks', { post_id: 1, blocks: [] }, client as any)
+    ).rejects.toThrow('block');
+  });
+});
+
+describe('rewrite_post_blocks — forwarding', () => {
+  let client: ReturnType<typeof makeMockClient>;
+  beforeEach(() => { client = makeMockClient(); vi.clearAllMocks(); });
+
+  it('calls replaceAllBlocks with the block array', async () => {
+    const blocks = [{ name: 'core/heading', attributes: { level: 1 } }];
+    await handleWriteTool('rewrite_post_blocks', { post_id: 1, blocks }, client as any);
+    expect(client.replaceAllBlocks).toHaveBeenCalledWith(1, expect.arrayContaining([
+      expect.objectContaining({ name: 'core/heading' }),
+    ]));
+  });
+
+  it('passes blocks through enrichBlocks', async () => {
+    const { enrichBlocks } = await import('../../../enrichers.js');
+    (enrichBlocks as ReturnType<typeof vi.fn>).mockClear();
+    await handleWriteTool('rewrite_post_blocks', {
+      post_id: 1, blocks: [{ name: 'core/heading', attributes: { level: 1 } }],
+    }, client as any);
+    expect(enrichBlocks).toHaveBeenCalled();
+  });
+
+  it('enriched attributes reach replaceAllBlocks', async () => {
+    await handleWriteTool('rewrite_post_blocks', {
+      post_id: 1, blocks: [{ name: 'core/heading', attributes: { level: 1 } }],
+    }, client as any);
+    const call = client.replaceAllBlocks.mock.calls[0] as unknown[];
+    const blocks = call[1] as Array<{ attributes: Record<string, unknown> }>;
+    expect(blocks[0].attributes).toMatchObject({ level: 1, enriched: true });
+  });
+});
+
+describe('rewrite_post_blocks — warnings', () => {
+  let client: ReturnType<typeof makeMockClient>;
+  beforeEach(() => { client = makeMockClient(); vi.clearAllMocks(); });
+
+  it('adds formatted_warnings when response has warnings', async () => {
+    client.replaceAllBlocks.mockResolvedValueOnce({
+      success: true, inserted: [], before_revision_id: 1, revision_id: 2,
+      warnings: [{ block: 'oldns/text', message: 'AVOID', suggested_replacement: 'core/paragraph' }],
+    });
+    const result = await handleWriteTool('rewrite_post_blocks', {
+      post_id: 1, blocks: [{ name: 'oldns/text' }],
+    }, client as any);
+    assertHasFormattedWarning(result, 'WARNING');
+  });
+
+  it('no formatted_warnings when response is clean', async () => {
+    const result = await handleWriteTool('rewrite_post_blocks', {
+      post_id: 1, blocks: [{ name: 'core/heading', attributes: { level: 1 } }],
+    }, client as any);
+    assertNoFormattedWarnings(result);
+  });
+});
+
+// ── revert_to_revision ────────────────────────────────────────────────────────
+
+describe('revert_to_revision — validation', () => {
+  let client: ReturnType<typeof makeMockClient>;
+  beforeEach(() => { client = makeMockClient(); vi.clearAllMocks(); });
+
+  it('requires post_id', async () => {
+    await expect(
+      handleWriteTool('revert_to_revision', { revision_id: 1 }, client as any)
+    ).rejects.toThrow('post_id');
+  });
+
+  it('requires revision_id', async () => {
+    await expect(
+      handleWriteTool('revert_to_revision', { post_id: 1 }, client as any)
+    ).rejects.toThrow('revision_id');
+  });
+});
+
+describe('revert_to_revision — forwarding', () => {
+  let client: ReturnType<typeof makeMockClient>;
+  beforeEach(() => { client = makeMockClient(); vi.clearAllMocks(); });
+
+  it('calls revertToRevision with correct args', async () => {
+    await handleWriteTool('revert_to_revision', { post_id: 1, revision_id: 456 }, client as any);
+    expect(client.revertToRevision).toHaveBeenCalledWith(1, 456);
+  });
+});