@gravitykit/block-mcp 2.0.0-beta

package/src/__tests__/tools/mutate/edit_block_tree.test.ts

@@ -0,0 +1,439 @@
+/**
+ * Tool tests: edit_block_tree (9 ops)
+ *
+ * Ops covered: update-attrs, update-html, replace-block, remove-block,
+ * wrap-in-group, unwrap-group, insert-child, duplicate, move.
+ *
+ * Each op has dedicated describe blocks covering:
+ *   - Validation (per-op required fields)
+ *   - Forwarding to client.mutateBlockTree
+ *   - Common: path/ref XOR, op enum, post_id required, integer-path shape
+ *   - Warning formatting (static_markup_stale_risk + preference warning)
+ */
+
+import { describe, it, expect, beforeEach } from 'vitest';
+import { handleMutateTool } from '../../../tools/mutate.js';
+import { makeMockClient } from '../../helpers/mock-client.js';
+import {
+  mutationUpdateAttrsResponse, mutationWithStaticWarning,
+} from '../../fixtures/rest-responses.js';
+import { assertMutationResponse } from '../../helpers/schema-asserts.js';
+
+// ── Common validation ─────────────────────────────────────────────────────────
+
+describe('edit_block_tree — common validation', () => {
+  let client: ReturnType<typeof makeMockClient>;
+  beforeEach(() => {
+    client = makeMockClient();
+    client.mutateBlockTree.mockResolvedValue(mutationUpdateAttrsResponse);
+  });
+
+  it('rejects unknown top-level tool name', async () => {
+    await expect(
+      handleMutateTool('not_a_real_tool', { post_id: 1, op: 'update-attrs', path: [0] }, client as any)
+    ).rejects.toThrow(/Unknown mutate tool/);
+  });
+
+  it('requires post_id', async () => {
+    await expect(
+      handleMutateTool('edit_block_tree', { op: 'update-attrs', path: [0], attributes: {} }, client as any)
+    ).rejects.toThrow(/post_id is required/);
+  });
+
+  it('rejects unknown op', async () => {
+    await expect(
+      handleMutateTool('edit_block_tree', { post_id: 1, op: 'frobnicate', path: [0] }, client as any)
+    ).rejects.toThrow(/op must be one of/);
+  });
+
+  it('rejects missing op', async () => {
+    await expect(
+      handleMutateTool('edit_block_tree', { post_id: 1, path: [0] }, client as any)
+    ).rejects.toThrow(/op must be one of/);
+  });
+
+  it('rejects both path and ref together', async () => {
+    await expect(
+      handleMutateTool('edit_block_tree', {
+        post_id: 1, op: 'remove-block', path: [0], ref: 'blk_a',
+      }, client as any)
+    ).rejects.toThrow(/path.*OR.*ref/i);
+  });
+
+  it('rejects when neither path nor ref is given', async () => {
+    await expect(
+      handleMutateTool('edit_block_tree', { post_id: 1, op: 'remove-block' }, client as any)
+    ).rejects.toThrow(/path.*or.*ref/i);
+  });
+
+  it('rejects non-array path', async () => {
+    await expect(
+      handleMutateTool('edit_block_tree', {
+        post_id: 1, op: 'remove-block', path: 'not-an-array',
+      }, client as any)
+    ).rejects.toThrow(/path must be an array of integers/);
+  });
+
+  it('rejects path with non-integer elements', async () => {
+    await expect(
+      handleMutateTool('edit_block_tree', {
+        post_id: 1, op: 'remove-block', path: [0, 1.5],
+      }, client as any)
+    ).rejects.toThrow(/path must contain only integers/);
+  });
+
+  it('rejects empty path', async () => {
+    await expect(
+      handleMutateTool('edit_block_tree', {
+        post_id: 1, op: 'remove-block', path: [],
+      }, client as any)
+    ).rejects.toThrow(/path must not be empty/);
+  });
+
+  it('forwards path verbatim to client.mutateBlockTree', async () => {
+    await handleMutateTool('edit_block_tree', {
+      post_id: 1, op: 'remove-block', path: [0, 2, 1],
+    }, client as any);
+    expect(client.mutateBlockTree).toHaveBeenCalledWith(1, expect.objectContaining({
+      op: 'remove-block', path: [0, 2, 1],
+    }));
+  });
+
+  it('forwards ref verbatim to client.mutateBlockTree', async () => {
+    await handleMutateTool('edit_block_tree', {
+      post_id: 1, op: 'remove-block', ref: 'blk_xyz',
+    }, client as any);
+    expect(client.mutateBlockTree).toHaveBeenCalledWith(1, expect.objectContaining({
+      op: 'remove-block', ref: 'blk_xyz',
+    }));
+  });
+});
+
+// ── op: update-attrs ──────────────────────────────────────────────────────────
+
+describe('edit_block_tree — update-attrs', () => {
+  let client: ReturnType<typeof makeMockClient>;
+  beforeEach(() => {
+    client = makeMockClient();
+    client.mutateBlockTree.mockResolvedValue(mutationUpdateAttrsResponse);
+  });
+
+  it('requires attributes object', async () => {
+    await expect(
+      handleMutateTool('edit_block_tree', { post_id: 1, op: 'update-attrs', path: [0] }, client as any)
+    ).rejects.toThrow(/attributes/);
+  });
+
+  it('forwards attributes to client', async () => {
+    await handleMutateTool('edit_block_tree', {
+      post_id: 1, op: 'update-attrs', path: [0], attributes: { level: 3 },
+    }, client as any);
+    expect(client.mutateBlockTree).toHaveBeenCalledWith(1, expect.objectContaining({
+      op: 'update-attrs', attributes: { level: 3 },
+    }));
+  });
+});
+
+// ── op: update-html ───────────────────────────────────────────────────────────
+
+describe('edit_block_tree — update-html', () => {
+  let client: ReturnType<typeof makeMockClient>;
+  beforeEach(() => {
+    client = makeMockClient();
+    client.mutateBlockTree.mockResolvedValue(mutationUpdateAttrsResponse);
+  });
+
+  it('requires innerHTML string', async () => {
+    await expect(
+      handleMutateTool('edit_block_tree', { post_id: 1, op: 'update-html', path: [0] }, client as any)
+    ).rejects.toThrow(/innerHTML/);
+  });
+
+  it('forwards innerHTML to client', async () => {
+    await handleMutateTool('edit_block_tree', {
+      post_id: 1, op: 'update-html', path: [0], innerHTML: '<p>New</p>',
+    }, client as any);
+    expect(client.mutateBlockTree).toHaveBeenCalledWith(1, expect.objectContaining({
+      op: 'update-html', innerHTML: '<p>New</p>',
+    }));
+  });
+
+  it('empty string innerHTML is forwarded (allowed)', async () => {
+    await handleMutateTool('edit_block_tree', {
+      post_id: 1, op: 'update-html', path: [0], innerHTML: '',
+    }, client as any);
+    expect(client.mutateBlockTree).toHaveBeenCalledWith(1, expect.objectContaining({
+      innerHTML: '',
+    }));
+  });
+});
+
+// ── op: replace-block ─────────────────────────────────────────────────────────
+
+describe('edit_block_tree — replace-block', () => {
+  let client: ReturnType<typeof makeMockClient>;
+  beforeEach(() => {
+    client = makeMockClient();
+    client.mutateBlockTree.mockResolvedValue(mutationUpdateAttrsResponse);
+  });
+
+  it('requires a block object with name', async () => {
+    await expect(
+      handleMutateTool('edit_block_tree', { post_id: 1, op: 'replace-block', path: [0] }, client as any)
+    ).rejects.toThrow(/"block" object.*"name"/);
+  });
+
+  it('rejects block missing name property', async () => {
+    await expect(
+      handleMutateTool('edit_block_tree', {
+        post_id: 1, op: 'replace-block', path: [0], block: { attributes: {} },
+      }, client as any)
+    ).rejects.toThrow(/name/);
+  });
+
+  it('forwards the block to client', async () => {
+    await handleMutateTool('edit_block_tree', {
+      post_id: 1, op: 'replace-block', path: [0],
+      block: { name: 'core/paragraph', attributes: { content: 'Hi' } },
+    }, client as any);
+    expect(client.mutateBlockTree).toHaveBeenCalledWith(1, expect.objectContaining({
+      op: 'replace-block', block: { name: 'core/paragraph', attributes: { content: 'Hi' } },
+    }));
+  });
+});
+
+// ── op: insert-child ──────────────────────────────────────────────────────────
+
+describe('edit_block_tree — insert-child', () => {
+  let client: ReturnType<typeof makeMockClient>;
+  beforeEach(() => {
+    client = makeMockClient();
+    client.mutateBlockTree.mockResolvedValue(mutationUpdateAttrsResponse);
+  });
+
+  it('requires a block object with name', async () => {
+    await expect(
+      handleMutateTool('edit_block_tree', { post_id: 1, op: 'insert-child', path: [0] }, client as any)
+    ).rejects.toThrow(/"block" object.*"name"/);
+  });
+
+  it('forwards integer position', async () => {
+    await handleMutateTool('edit_block_tree', {
+      post_id: 1, op: 'insert-child', path: [0],
+      block: { name: 'core/paragraph' }, position: 2,
+    }, client as any);
+    expect(client.mutateBlockTree).toHaveBeenCalledWith(1, expect.objectContaining({
+      op: 'insert-child', position: 2,
+    }));
+  });
+
+  it('forwards "start" position', async () => {
+    await handleMutateTool('edit_block_tree', {
+      post_id: 1, op: 'insert-child', path: [0],
+      block: { name: 'core/paragraph' }, position: 'start',
+    }, client as any);
+    expect(client.mutateBlockTree).toHaveBeenCalledWith(1, expect.objectContaining({
+      position: 'start',
+    }));
+  });
+
+  it('forwards "end" position', async () => {
+    await handleMutateTool('edit_block_tree', {
+      post_id: 1, op: 'insert-child', path: [0],
+      block: { name: 'core/paragraph' }, position: 'end',
+    }, client as any);
+    expect(client.mutateBlockTree).toHaveBeenCalledWith(1, expect.objectContaining({
+      position: 'end',
+    }));
+  });
+
+  it('rejects invalid position string', async () => {
+    await expect(
+      handleMutateTool('edit_block_tree', {
+        post_id: 1, op: 'insert-child', path: [0],
+        block: { name: 'core/paragraph' }, position: 'middle',
+      }, client as any)
+    ).rejects.toThrow(/position must be/);
+  });
+
+  it('rejects non-integer numeric position', async () => {
+    await expect(
+      handleMutateTool('edit_block_tree', {
+        post_id: 1, op: 'insert-child', path: [0],
+        block: { name: 'core/paragraph' }, position: 1.5,
+      }, client as any)
+    ).rejects.toThrow(/position must be/);
+  });
+
+  it('omits position when not provided', async () => {
+    await handleMutateTool('edit_block_tree', {
+      post_id: 1, op: 'insert-child', path: [0], block: { name: 'core/paragraph' },
+    }, client as any);
+    const arg = client.mutateBlockTree.mock.calls[0]![1] as Record<string, unknown>;
+    expect('position' in arg).toBe(false);
+  });
+});
+
+// ── op: wrap-in-group ─────────────────────────────────────────────────────────
+
+describe('edit_block_tree — wrap-in-group', () => {
+  let client: ReturnType<typeof makeMockClient>;
+  beforeEach(() => {
+    client = makeMockClient();
+    client.mutateBlockTree.mockResolvedValue(mutationUpdateAttrsResponse);
+  });
+
+  it('works without a wrapper (defaults applied server-side)', async () => {
+    await handleMutateTool('edit_block_tree', { post_id: 1, op: 'wrap-in-group', path: [0] }, client as any);
+    expect(client.mutateBlockTree).toHaveBeenCalled();
+    const arg = client.mutateBlockTree.mock.calls[0]![1] as Record<string, unknown>;
+    expect('wrapper' in arg).toBe(false);
+  });
+
+  it('forwards custom wrapper when provided', async () => {
+    await handleMutateTool('edit_block_tree', {
+      post_id: 1, op: 'wrap-in-group', path: [0],
+      wrapper: { name: 'core/cover', attributes: { url: 'x.jpg' } },
+    }, client as any);
+    expect(client.mutateBlockTree).toHaveBeenCalledWith(1, expect.objectContaining({
+      wrapper: { name: 'core/cover', attributes: { url: 'x.jpg' } },
+    }));
+  });
+});
+
+// ── ops with no payload: remove-block, unwrap-group, duplicate ────────────────
+
+describe('edit_block_tree — payload-less ops', () => {
+  let client: ReturnType<typeof makeMockClient>;
+  beforeEach(() => {
+    client = makeMockClient();
+    client.mutateBlockTree.mockResolvedValue(mutationUpdateAttrsResponse);
+  });
+
+  it.each(['remove-block', 'unwrap-group', 'duplicate'] as const)(
+    'forwards %s with no extra payload',
+    async (op) => {
+      await handleMutateTool('edit_block_tree', { post_id: 1, op, path: [0] }, client as any);
+      expect(client.mutateBlockTree).toHaveBeenCalledWith(1, expect.objectContaining({
+        op, path: [0],
+      }));
+    }
+  );
+});
+
+// ── op: move ──────────────────────────────────────────────────────────────────
+
+describe('edit_block_tree — move', () => {
+  let client: ReturnType<typeof makeMockClient>;
+  beforeEach(() => {
+    client = makeMockClient();
+    client.mutateBlockTree.mockResolvedValue(mutationUpdateAttrsResponse);
+  });
+
+  it('requires destination or destination_ref', async () => {
+    await expect(
+      handleMutateTool('edit_block_tree', { post_id: 1, op: 'move', path: [0] }, client as any)
+    ).rejects.toThrow(/destination/);
+  });
+
+  it('rejects both destination and destination_ref together', async () => {
+    await expect(
+      handleMutateTool('edit_block_tree', {
+        post_id: 1, op: 'move', path: [0],
+        destination: [1], destination_ref: 'blk_b',
+      }, client as any)
+    ).rejects.toThrow(/destination.*OR.*destination_ref/i);
+  });
+
+  it('forwards destination path', async () => {
+    await handleMutateTool('edit_block_tree', {
+      post_id: 1, op: 'move', path: [0], destination: [2],
+    }, client as any);
+    expect(client.mutateBlockTree).toHaveBeenCalledWith(1, expect.objectContaining({
+      op: 'move', destination: [2],
+    }));
+  });
+
+  it('forwards destination_ref', async () => {
+    await handleMutateTool('edit_block_tree', {
+      post_id: 1, op: 'move', path: [0], destination_ref: 'blk_target',
+    }, client as any);
+    expect(client.mutateBlockTree).toHaveBeenCalledWith(1, expect.objectContaining({
+      op: 'move', destination_ref: 'blk_target',
+    }));
+  });
+
+  it('rejects non-integer destination', async () => {
+    await expect(
+      handleMutateTool('edit_block_tree', {
+        post_id: 1, op: 'move', path: [0], destination: [1.5],
+      }, client as any)
+    ).rejects.toThrow(/integers/);
+  });
+
+  it('forwards integer count', async () => {
+    await handleMutateTool('edit_block_tree', {
+      post_id: 1, op: 'move', path: [0], destination: [2], count: 3,
+    }, client as any);
+    expect(client.mutateBlockTree).toHaveBeenCalledWith(1, expect.objectContaining({
+      count: 3,
+    }));
+  });
+
+  it('rejects count < 1', async () => {
+    await expect(
+      handleMutateTool('edit_block_tree', {
+        post_id: 1, op: 'move', path: [0], destination: [2], count: 0,
+      }, client as any)
+    ).rejects.toThrow(/positive integer/);
+  });
+
+  it('rejects non-integer count', async () => {
+    await expect(
+      handleMutateTool('edit_block_tree', {
+        post_id: 1, op: 'move', path: [0], destination: [2], count: 1.5,
+      }, client as any)
+    ).rejects.toThrow(/positive integer/);
+  });
+});
+
+// ── Response shape ────────────────────────────────────────────────────────────
+
+describe('edit_block_tree — response shape', () => {
+  let client: ReturnType<typeof makeMockClient>;
+  beforeEach(() => {
+    client = makeMockClient();
+    client.mutateBlockTree.mockResolvedValue(mutationUpdateAttrsResponse);
+  });
+
+  it('returns a valid MutationResponse', async () => {
+    const result = await handleMutateTool('edit_block_tree', {
+      post_id: 1, op: 'update-attrs', path: [0], attributes: { level: 3 },
+    }, client as any);
+    assertMutationResponse(result);
+  });
+});
+
+// ── Warning formatting ────────────────────────────────────────────────────────
+
+describe('edit_block_tree — warning formatting', () => {
+  let client: ReturnType<typeof makeMockClient>;
+  beforeEach(() => { client = makeMockClient(); });
+
+  it('formats static_markup_stale_risk warnings', async () => {
+    client.mutateBlockTree.mockResolvedValueOnce(mutationWithStaticWarning as any);
+    const result = await handleMutateTool('edit_block_tree', {
+      post_id: 1, op: 'update-attrs', path: [0], attributes: { url: 'x' },
+    }, client as any) as { formatted_warnings: string[] };
+    expect(Array.isArray(result.formatted_warnings)).toBe(true);
+    expect(result.formatted_warnings.length).toBeGreaterThan(0);
+    expect(result.formatted_warnings[0]).toMatch(/WARNING|static/i);
+  });
+
+  it('omits formatted_warnings when response has no warnings', async () => {
+    const result = await handleMutateTool('edit_block_tree', {
+      post_id: 1, op: 'update-attrs', path: [0], attributes: { level: 3 },
+    }, client as any) as Record<string, unknown>;
+    expect('formatted_warnings' in result).toBe(false);
+  });
+});

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

@@ -0,0 +1,105 @@
+/**
+ * Tool tests: edit_block_tree — ref vs path addressing
+ *
+ * Covers:
+ *   - ref forwarded when ref is provided (path absent)
+ *   - path forwarded when path is provided (ref absent)
+ *   - both path and ref rejected
+ *   - neither path nor ref rejected
+ *   - empty path array rejected
+ *   - path integer-array validation still applies with ref
+ *   - move: destination_ref accepted instead of destination path
+ *   - move: both destination + destination_ref rejected
+ *   - move: neither destination nor destination_ref rejected
+ */
+
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { handleMutateTool } from '../../../tools/mutate.js';
+import { makeMockClient } from '../../helpers/mock-client.js';
+import { mutationUpdateAttrsResponse } from '../../fixtures/rest-responses.js';
+
+describe('edit_block_tree — ref vs path', () => {
+  let client: ReturnType<typeof makeMockClient>;
+  beforeEach(() => {
+    client = makeMockClient();
+    client.mutateBlockTree.mockResolvedValue(mutationUpdateAttrsResponse);
+    vi.clearAllMocks();
+  });
+
+  it('forwards path when only path is provided', async () => {
+    await handleMutateTool('edit_block_tree', {
+      post_id: 1, op: 'update-attrs', path: [0, 1], attributes: { level: 2 },
+    }, client as any);
+    const call = client.mutateBlockTree.mock.calls[0]![1] as Record<string, unknown>;
+    expect(call.path).toEqual([0, 1]);
+    expect(call.ref).toBeUndefined();
+  });
+
+  it('forwards ref when only ref is provided', async () => {
+    await handleMutateTool('edit_block_tree', {
+      post_id: 1, op: 'update-attrs', ref: 'blk_target', attributes: { level: 2 },
+    }, client as any);
+    const call = client.mutateBlockTree.mock.calls[0]![1] as Record<string, unknown>;
+    expect(call.ref).toBe('blk_target');
+    expect(call.path).toBeUndefined();
+  });
+
+  it('rejects when both path and ref are provided', async () => {
+    await expect(
+      handleMutateTool('edit_block_tree', {
+        post_id: 1, op: 'update-attrs', path: [0], ref: 'blk_x', attributes: {},
+      }, client as any)
+    ).rejects.toThrow(/path.*OR.*ref.*not both/i);
+  });
+
+  it('rejects when neither path nor ref is provided', async () => {
+    await expect(
+      handleMutateTool('edit_block_tree', { post_id: 1, op: 'update-attrs', attributes: {} }, client as any)
+    ).rejects.toThrow(/Provide either "path" or "ref"/);
+  });
+
+  it('rejects empty path array', async () => {
+    await expect(
+      handleMutateTool('edit_block_tree', { post_id: 1, op: 'update-attrs', path: [], attributes: {} }, client as any)
+    ).rejects.toThrow(/path must not be empty/);
+  });
+
+  it('still validates path is an array of integers', async () => {
+    await expect(
+      handleMutateTool('edit_block_tree', {
+        post_id: 1, op: 'update-attrs', path: 'not-array', attributes: {},
+      }, client as any)
+    ).rejects.toThrow(/must be an array of integers/);
+  });
+});
+
+describe('edit_block_tree — move: destination_ref', () => {
+  let client: ReturnType<typeof makeMockClient>;
+  beforeEach(() => {
+    client = makeMockClient();
+    client.mutateBlockTree.mockResolvedValue({ ...mutationUpdateAttrsResponse, op: 'move' as any });
+    vi.clearAllMocks();
+  });
+
+  it('accepts destination_ref instead of destination path', async () => {
+    await handleMutateTool('edit_block_tree', {
+      post_id: 1, op: 'move', ref: 'blk_source', destination_ref: 'blk_dest',
+    }, client as any);
+    const call = client.mutateBlockTree.mock.calls[0]![1] as Record<string, unknown>;
+    expect(call.destination_ref).toBe('blk_dest');
+  });
+
+  it('rejects when no destination or destination_ref provided', async () => {
+    await expect(
+      handleMutateTool('edit_block_tree', { post_id: 1, op: 'move', ref: 'blk_x' }, client as any)
+    ).rejects.toThrow(/move requires/);
+  });
+
+  it('rejects when both destination path AND destination_ref are provided', async () => {
+    await expect(
+      handleMutateTool('edit_block_tree', {
+        post_id: 1, op: 'move', ref: 'blk_src', destination: [3], destination_ref: 'blk_dest',
+      }, client as any)
+    ).rejects.toThrow(/destination.*OR.*destination_ref.*not both/i);
+  });
+});

package/src/__tests__/tools/patterns/insert_pattern.test.ts

@@ -0,0 +1,117 @@
+/**
+ * Tool tests: insert_pattern
+ *
+ * Covers:
+ *   - Validation: post_id required, pattern_id required
+ *   - Default synced=true
+ *   - synced=false forwarded
+ *   - after_top_level → after
+ *   - before_top_level → before
+ *   - String pattern_id accepted
+ *   - Response note for synced insertion
+ *   - Response note for non-synced insertion
+ *   - Unknown tool throws
+ */
+
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { handlePatternTool } from '../../../tools/patterns.js';
+import { makeMockClient } from '../../helpers/mock-client.js';
+import { patternInsertResponse } from '../../fixtures/rest-responses.js';
+
+describe('insert_pattern — validation', () => {
+  let client: ReturnType<typeof makeMockClient>;
+  beforeEach(() => { client = makeMockClient(); vi.clearAllMocks(); });
+
+  it('requires post_id', async () => {
+    await expect(handlePatternTool('insert_pattern', { pattern_id: 1 }, client as any))
+      .rejects.toThrow('post_id');
+  });
+
+  it('requires pattern_id', async () => {
+    await expect(handlePatternTool('insert_pattern', { post_id: 1 }, client as any))
+      .rejects.toThrow('pattern_id');
+  });
+
+  it('throws on unknown tool name', async () => {
+    await expect(handlePatternTool('unknown_tool', { post_id: 1, pattern_id: 1 }, client as any))
+      .rejects.toThrow('Unknown pattern tool');
+  });
+});
+
+describe('insert_pattern — request shape', () => {
+  let client: ReturnType<typeof makeMockClient>;
+  beforeEach(() => {
+    client = makeMockClient();
+    client.insertPattern.mockResolvedValue(patternInsertResponse);
+    vi.clearAllMocks();
+  });
+
+  it('calls client with default synced=true', async () => {
+    await handlePatternTool('insert_pattern', { post_id: 1, pattern_id: 123 }, client as any);
+    expect(client.insertPattern).toHaveBeenCalledWith(1, expect.objectContaining({
+      pattern_id: 123, synced: true,
+    }));
+  });
+
+  it('passes synced=false through', async () => {
+    await handlePatternTool('insert_pattern', { post_id: 1, pattern_id: 123, synced: false }, client as any);
+    expect(client.insertPattern).toHaveBeenCalledWith(1, expect.objectContaining({ synced: false }));
+  });
+
+  it('maps after_top_level → after in client call', async () => {
+    await handlePatternTool('insert_pattern', { post_id: 1, pattern_id: 123, after_top_level: 3 }, client as any);
+    expect(client.insertPattern).toHaveBeenCalledWith(1, expect.objectContaining({ after: 3 }));
+  });
+
+  it('maps before_top_level → before in client call', async () => {
+    await handlePatternTool('insert_pattern', { post_id: 1, pattern_id: 123, before_top_level: 2 }, client as any);
+    expect(client.insertPattern).toHaveBeenCalledWith(1, expect.objectContaining({ before: 2 }));
+  });
+
+  it('accepts a string pattern_id', async () => {
+    await handlePatternTool('insert_pattern', { post_id: 1, pattern_id: 'my-pattern-slug' }, client as any);
+    expect(client.insertPattern).toHaveBeenCalledWith(1, expect.objectContaining({
+      pattern_id: 'my-pattern-slug',
+    }));
+  });
+});
+
+describe('insert_pattern — response shape', () => {
+  let client: ReturnType<typeof makeMockClient>;
+  beforeEach(() => {
+    client = makeMockClient();
+    vi.clearAllMocks();
+  });
+
+  it('adds a synced-reference note when pattern was inserted as synced', async () => {
+    client.insertPattern.mockResolvedValue(patternInsertResponse); // synced: true
+    const result = await handlePatternTool('insert_pattern', { post_id: 1, pattern_id: 123 }, client as any) as any;
+    expect(result.note).toContain('synced reference');
+  });
+
+  it('adds an inline/independent note when pattern was inserted non-synced', async () => {
+    client.insertPattern.mockResolvedValue({
+      ...patternInsertResponse,
+      synced: false,
+      inserted: [{ index: 5, name: 'core/heading' }],
+    });
+    const result = await handlePatternTool('insert_pattern', {
+      post_id: 1, pattern_id: 123, synced: false,
+    }, client as any) as any;
+    expect(result.note).toContain('inline');
+    expect(result.note).toContain('independent');
+  });
+
+  it('success flag is present', async () => {
+    client.insertPattern.mockResolvedValue(patternInsertResponse);
+    const result = await handlePatternTool('insert_pattern', { post_id: 1, pattern_id: 123 }, client as any) as any;
+    expect(result.success).toBe(true);
+  });
+
+  it('revision IDs are present', async () => {
+    client.insertPattern.mockResolvedValue(patternInsertResponse);
+    const result = await handlePatternTool('insert_pattern', { post_id: 1, pattern_id: 123 }, client as any) as any;
+    expect(result.before_revision_id).toBe(100);
+    expect(result.revision_id).toBe(101);
+  });
+});