@gravitykit/block-mcp 2.0.0-beta

package/src/__tests__/helpers/mock-client.ts

@@ -0,0 +1,185 @@
+/**
+ * Typed mock for WordPressBlockClient.
+ *
+ * Returns a vi.fn() stub for every public client method. Tests override
+ * individual methods with .mockResolvedValueOnce() as needed.
+ *
+ * Usage:
+ *   import { makeMockClient } from '../helpers/mock-client.js';
+ *   const client = makeMockClient();
+ *   client.getPageBlocks.mockResolvedValueOnce(pageBlocksResponse);
+ */
+import { vi } from 'vitest';
+
+/** The full shape of the mock client returned by makeMockClient(). */
+export type MockClient = ReturnType<typeof makeMockClient>;
+
+/**
+ * Build a fresh mock client with all methods stubbed as vi.fn().
+ * Each method returns a resolved promise with a sensible empty/success value.
+ * Override per-test with .mockResolvedValueOnce().
+ */
+export function makeMockClient() {
+  return {
+    // ── Discovery ────────────────────────────────────────────────────────
+    getBlockTypes: vi.fn().mockResolvedValue(
+      { block_types: [] }
+    ),
+    getPatterns: vi.fn().mockResolvedValue(
+      { patterns: [] }
+    ),
+    getPattern: vi.fn().mockResolvedValue({ id: 1, name: 'Test Pattern' }),
+    searchPatterns: vi.fn().mockResolvedValue(
+      { patterns: [] }
+    ),
+    getSiteUsage: vi.fn().mockResolvedValue(
+      { block_usage: {}, namespace_totals: {}, pattern_references: {}, legacy_patterns: [] }
+    ),
+    resolveUrl: vi.fn().mockResolvedValue({
+      post_id: 1,
+      post_type: 'page',
+      title: 'Test Page',
+      status: 'publish',
+      slug: 'test-page',
+      edit_url: 'https://example.test/wp-admin/post.php?post=1&action=edit',
+    }),
+    findPosts: vi.fn().mockResolvedValue(
+      { posts: [], count: 0, total: 0, total_pages: 0, page: 1, per_page: 20 }
+    ),
+    getPostInfo: vi.fn().mockResolvedValue({
+      post_id: 1, title: 'Test', slug: 'test', post_type: 'page',
+      post_status: 'publish', post_url: '', edit_url: '',
+      modified: '2026-01-01', created: '2026-01-01',
+      parent_id: 0, author: { id: 1, display_name: 'Admin' },
+      mime_type: '', comment_count: 0,
+    }),
+    scanStorageModes: vi.fn().mockResolvedValue({
+      scanned_posts: 0, unique_blocks: 0, classification: {},
+      dual_count: 0, dynamic_count: 0, static_count: 0,
+    }),
+
+    // ── Read ─────────────────────────────────────────────────────────────
+    getPageBlocks: vi.fn().mockResolvedValue(
+      { blocks: [], summary: undefined }
+    ),
+    getBlock: vi.fn().mockResolvedValue({
+      success: true,
+      saved: {
+        flat_index: 0, block_name: 'core/paragraph',
+        attributes: {}, inner_html: '<p></p>', is_dynamic: false,
+      },
+    }),
+
+    // ── Write ────────────────────────────────────────────────────────────
+    updateBlock: vi.fn().mockResolvedValue({
+      success: true,
+      block: { index: 0, name: 'core/paragraph', attributes: {} },
+      saved: {
+        flat_index: 0, block_name: 'core/paragraph',
+        attributes: {}, inner_html: '<p></p>', is_dynamic: false,
+      },
+      before_revision_id: 1,
+      revision_id: 2,
+    }),
+    updateBlockByRef: vi.fn().mockResolvedValue({
+      success: true,
+      block: { index: 0, name: 'core/paragraph', attributes: {}, ref: 'blk_test0001' },
+      saved: {
+        flat_index: 0, block_name: 'core/paragraph',
+        attributes: {}, inner_html: '<p></p>', is_dynamic: false, ref: 'blk_test0001',
+      },
+      before_revision_id: 1,
+      revision_id: 2,
+    }),
+    updateBlocksBatch: vi.fn().mockResolvedValue({
+      success: true, count: 0, results: [], before_revision_id: 1, revision_id: 2,
+    }),
+    insertBlocks: vi.fn().mockResolvedValue({
+      success: true,
+      inserted: [{ index: 0, name: 'core/paragraph' }],
+      warnings: [],
+      before_revision_id: 1,
+      revision_id: 2,
+    }),
+    deleteBlock: vi.fn().mockResolvedValue(
+      { success: true, removed: 1, before_revision_id: 1, revision_id: 2 }
+    ),
+    deleteBlockByRef: vi.fn().mockResolvedValue(
+      { success: true, removed: 1, before_revision_id: 1, revision_id: 2 }
+    ),
+    replaceBlocksRange: vi.fn().mockResolvedValue({
+      success: true, removed: 0,
+      inserted: [{ index: 0, name: 'core/paragraph' }],
+      warnings: [],
+      before_revision_id: 1, revision_id: 2,
+    }),
+    replaceAllBlocks: vi.fn().mockResolvedValue({
+      success: true,
+      inserted: [],
+      warnings: [],
+      before_revision_id: 1,
+      revision_id: 2,
+    }),
+    revertToRevision: vi.fn().mockResolvedValue({ success: true, revision_id: 1 }),
+
+    // ── Mutation ─────────────────────────────────────────────────────────
+    mutateBlockTree: vi.fn().mockResolvedValue({
+      success: true,
+      op: 'update-attrs' as const,
+      path: [0],
+      block: { name: 'core/paragraph', attributes: {} },
+      warnings: [],
+      before_revision_id: 1,
+      revision_id: 2,
+    }),
+
+    // ── Pattern ──────────────────────────────────────────────────────────
+    insertPattern: vi.fn().mockResolvedValue({
+      success: true,
+      inserted: { index: 0, name: 'core/block', attributes: { ref: 1 }, synced: true },
+      pattern_name: 'Test Pattern',
+      synced: true,
+      before_revision_id: 1,
+      revision_id: 2,
+    }),
+
+    // ── Post lifecycle ────────────────────────────────────────────────────
+    createPost: vi.fn().mockResolvedValue({
+      success: true, id: 1, post_type: 'post', status: 'draft',
+      title: 'Test Post', slug: 'test-post',
+      permalink: 'https://example.test/test-post/',
+      edit_link: '', before_revision_id: null, revision_id: null, warnings: [],
+    }),
+    updatePost: vi.fn().mockResolvedValue({
+      success: true, id: 1, post_type: 'post', status: 'publish',
+      title: 'Test Post', slug: 'test-post',
+      permalink: 'https://example.test/test-post/',
+      edit_link: '', before_revision_id: null, revision_id: null, warnings: [],
+      transitioned_to_publish: true,
+    }),
+
+    // ── Terms ─────────────────────────────────────────────────────────────
+    listTerms: vi.fn().mockResolvedValue(
+      { taxonomy: 'category', total: 0, page: 1, per_page: 100, terms: [] }
+    ),
+
+    // ── Media ─────────────────────────────────────────────────────────────
+    uploadMedia: vi.fn().mockResolvedValue({
+      success: true, id: 1, title: 'test.png', filename: 'test.png',
+      url: 'https://example.test/test.png',
+      source_url: 'https://example.test/test.png',
+      mime_type: 'image/png', alt_text: '', post_parent: 0,
+    }),
+
+    // ── Yoast ─────────────────────────────────────────────────────────────
+    getYoastSEO: vi.fn().mockResolvedValue({
+      post_id: 1, title: '', description: '', noindex: null,
+      seo_score: null, readability_score: null, inclusive_language_score: null,
+    }),
+    updateYoastSEO: vi.fn().mockResolvedValue({
+      post_id: 1, title: 'Updated', description: '', noindex: null,
+      seo_score: 80, readability_score: 70, inclusive_language_score: null,
+    }),
+    bulkUpdateYoastSEO: vi.fn().mockResolvedValue([]),
+  };
+}

package/src/__tests__/helpers/request-matchers.ts

@@ -0,0 +1,88 @@
+/**
+ * Assertion helpers for tool-layer test assertions.
+ *
+ * Provide lean wrappers that express domain intent rather than raw vitest
+ * matcher chains, making test bodies more readable.
+ */
+import { expect } from 'vitest';
+import type { MockClient } from './mock-client.js';
+
+// ── Tool result helpers ──────────────────────────────────────────────────────
+
+/**
+ * Assert a tool result signals success and has the expected top-level keys.
+ */
+export function assertToolSuccess(
+  result: unknown,
+  requiredKeys: string[] = ['success']
+): void {
+  expect(result).toBeDefined();
+  expect(typeof result).toBe('object');
+  const r = result as Record<string, unknown>;
+  for (const key of requiredKeys) {
+    expect(r, `result must have key "${key}"`).toHaveProperty(key);
+  }
+  if ('success' in r) {
+    expect(r.success).toBe(true);
+  }
+}
+
+/**
+ * Assert a tool result contains formatted_warnings with at least one entry
+ * that matches the expected substring.
+ */
+export function assertHasFormattedWarning(result: unknown, containing: string): void {
+  const r = result as Record<string, unknown>;
+  expect(r.formatted_warnings, 'formatted_warnings must be defined').toBeDefined();
+  const warnings = r.formatted_warnings as string[];
+  expect(Array.isArray(warnings)).toBe(true);
+  expect(warnings.length).toBeGreaterThan(0);
+  const found = warnings.some((w) => w.includes(containing));
+  expect(found, `No warning contains "${containing}". Got: ${JSON.stringify(warnings)}`).toBe(true);
+}
+
+/**
+ * Assert a tool result has NO formatted_warnings (clean path).
+ */
+export function assertNoFormattedWarnings(result: unknown): void {
+  const r = result as Record<string, unknown>;
+  expect(r.formatted_warnings).toBeUndefined();
+}
+
+// ── Client call helpers ──────────────────────────────────────────────────────
+
+/**
+ * Assert a named client method was called exactly once with the given args.
+ * Passes args to toHaveBeenCalledWith — supports asymmetric matchers.
+ */
+export function assertClientCalled(
+  client: MockClient,
+  method: keyof MockClient,
+  ...expectedArgs: unknown[]
+): void {
+  const fn = client[method] as ReturnType<typeof import('vitest').vi.fn>;
+  expect(fn).toHaveBeenCalledTimes(1);
+  if (expectedArgs.length > 0) {
+    expect(fn).toHaveBeenCalledWith(...expectedArgs);
+  }
+}
+
+/**
+ * Assert a named client method was NOT called.
+ */
+export function assertClientNotCalled(client: MockClient, method: keyof MockClient): void {
+  const fn = client[method] as ReturnType<typeof import('vitest').vi.fn>;
+  expect(fn).not.toHaveBeenCalled();
+}
+
+// ── Revision pair helper ──────────────────────────────────────────────────────
+
+/**
+ * Assert result has both revision IDs with before < after (sanity check).
+ */
+export function assertRevisionPair(result: unknown): void {
+  const r = result as Record<string, unknown>;
+  expect(typeof r.before_revision_id, 'before_revision_id must be number').toBe('number');
+  expect(typeof r.revision_id, 'revision_id must be number').toBe('number');
+  expect(r.revision_id as number).toBeGreaterThan(r.before_revision_id as number);
+}

package/src/__tests__/helpers/schema-asserts.ts

@@ -0,0 +1,132 @@
+/**
+ * Runtime shape-checking helpers.
+ *
+ * Zero new dependencies — uses typeof + key-presence to validate objects
+ * match the core interfaces from src/types.ts.
+ *
+ * These are assertion helpers for tests: they throw (via Vitest's expect)
+ * when an object is missing required keys or has a key of the wrong primitive
+ * type.
+ *
+ * Usage:
+ *   assertSavedBlock(result.saved);
+ *   assertBlock(blocks[0]);
+ */
+import { expect } from 'vitest';
+
+// ── Generic key-presence check ───────────────────────────────────────────────
+
+/**
+ * Assert that `value` is a non-null object containing all listed keys.
+ * Fails the test with a descriptive message when any key is absent.
+ */
+export function assertHasKeys<T extends object>(
+  value: unknown,
+  keys: (keyof T)[],
+  label = 'object'
+): asserts value is T {
+  // toBeDefined() only fails on undefined; null passes silently AND
+  // `typeof null === 'object'` so the type check below would also pass,
+  // letting downstream code read keys off null and crash with a
+  // less-informative message. Reject null explicitly first.
+  expect(value, `${label} must not be null/undefined`).not.toBeNull();
+  expect(value, `${label} must not be null/undefined`).toBeDefined();
+  expect(typeof value, `${label} must be an object`).toBe('object');
+  const obj = value as unknown as Record<string, unknown>;
+  for (const key of keys as string[]) {
+    expect(obj, `${label} must have key "${key}"`).toHaveProperty(key);
+  }
+}
+
+// ── Interface-specific assertions ────────────────────────────────────────────
+
+/**
+ * Assert `value` conforms to the SavedBlock interface.
+ * Checks: flat_index (number), block_name (string), attributes (object),
+ * inner_html (string), is_dynamic (boolean).
+ */
+export function assertSavedBlock(value: unknown): void {
+  assertHasKeys(value, ['flat_index', 'block_name', 'attributes', 'inner_html', 'is_dynamic'], 'SavedBlock');
+  const b = value as unknown as Record<string, unknown>;
+  expect(typeof b['flat_index'], 'SavedBlock.flat_index must be number').toBe('number');
+  expect(typeof b['block_name'], 'SavedBlock.block_name must be string').toBe('string');
+  expect(typeof b['attributes'], 'SavedBlock.attributes must be object').toBe('object');
+  expect(typeof b['inner_html'], 'SavedBlock.inner_html must be string').toBe('string');
+  expect(typeof b['is_dynamic'], 'SavedBlock.is_dynamic must be boolean').toBe('boolean');
+}
+
+/**
+ * Assert `value` conforms to the Block interface.
+ * Checks: index (number), name (string), attributes (object).
+ */
+export function assertBlock(value: unknown): void {
+  assertHasKeys(value, ['index', 'name', 'attributes'], 'Block');
+  const b = value as unknown as Record<string, unknown>;
+  expect(typeof b['index'], 'Block.index must be number').toBe('number');
+  expect(typeof b['name'], 'Block.name must be string').toBe('string');
+  expect(b['name'] as string).toMatch(/^\w[\w-]*\/[\w-]+$/);
+  expect(typeof b['attributes'], 'Block.attributes must be object').toBe('object');
+}
+
+/**
+ * Assert `value` conforms to BlockUpdateResponse.
+ */
+export function assertBlockUpdateResponse(value: unknown): void {
+  assertHasKeys(value, ['success', 'block', 'saved', 'before_revision_id', 'revision_id'], 'BlockUpdateResponse');
+  const r = value as unknown as Record<string, unknown>;
+  expect(r['success']).toBe(true);
+  assertSavedBlock(r['saved']);
+  expect(typeof r['before_revision_id'], 'before_revision_id must be number').toBe('number');
+  expect(typeof r['revision_id'], 'revision_id must be number').toBe('number');
+}
+
+/**
+ * Assert `value` conforms to BlockWriteResponse (insert / replace-all).
+ */
+export function assertBlockWriteResponse(value: unknown): void {
+  assertHasKeys(value, ['success', 'inserted', 'warnings', 'before_revision_id', 'revision_id'], 'BlockWriteResponse');
+  const r = value as unknown as Record<string, unknown>;
+  expect(r['success']).toBe(true);
+  expect(Array.isArray(r['inserted']), 'inserted must be an array').toBe(true);
+  expect(Array.isArray(r['warnings']), 'warnings must be an array').toBe(true);
+}
+
+/**
+ * Assert `value` conforms to MutationResponse.
+ */
+export function assertMutationResponse(value: unknown): void {
+  assertHasKeys(value, ['success', 'op', 'path', 'warnings', 'before_revision_id', 'revision_id'], 'MutationResponse');
+  const r = value as unknown as Record<string, unknown>;
+  expect(r['success']).toBe(true);
+  expect(typeof r['op']).toBe('string');
+  expect(Array.isArray(r['path'])).toBe(true);
+}
+
+/**
+ * Assert `value` is a valid PreferenceWarning.
+ */
+export function assertPreferenceWarning(value: unknown): void {
+  assertHasKeys(value, ['block', 'message'], 'PreferenceWarning');
+  const w = value as unknown as Record<string, unknown>;
+  expect(typeof w['block']).toBe('string');
+  expect(typeof w['message']).toBe('string');
+}
+
+/**
+ * Assert `value` conforms to PostMutationResponse.
+ */
+export function assertPostMutationResponse(value: unknown): void {
+  assertHasKeys(value, ['success', 'id', 'post_type', 'status', 'title', 'slug', 'permalink'], 'PostMutationResponse');
+  const r = value as unknown as Record<string, unknown>;
+  expect(r['success']).toBe(true);
+  expect(typeof r['id']).toBe('number');
+}
+
+/**
+ * Assert `value` conforms to YoastSEOMeta.
+ */
+export function assertYoastSEOMeta(value: unknown): void {
+  assertHasKeys(value, ['post_id'], 'YoastSEOMeta');
+  const r = value as unknown as Record<string, unknown>;
+  expect(typeof r['post_id']).toBe('number');
+}

package/src/__tests__/integration/concurrency.test.ts

@@ -0,0 +1,129 @@
+/**
+ * Integration: ETag / If-Match stale-revision rejection
+ *
+ * The plugin's PATCH endpoint accepts an `if_match` body field carrying a
+ * revision_id. Sending two writes with the SAME revision_id as the pre-edit
+ * baseline should cause the second write to be rejected with HTTP 412
+ * (stale_revision) because the first write already bumped the revision.
+ *
+ * Capability detection: if the live plugin does not enforce `if_match` (i.e.
+ * the second write with a stale revision succeeds with 200), we emit a
+ * console.log and the test passes — the plugin just doesn't implement this
+ * guard yet. We don't assert a hard failure because the gkclone site may be
+ * running an older plugin version that pre-dates this feature.
+ *
+ * The "correct If-Match succeeds" test is always valid regardless of version.
+ */
+
+import { describe, it, expect } from 'vitest';
+import axios from 'axios';
+import { makeLiveClient, skipUnlessLive, withTestPost, LIVE_ENV } from './setup.js';
+
+const skip = skipUnlessLive();
+
+/** Fire a raw PATCH to /posts/{id}/blocks/{index} with an explicit if_match field. */
+async function patchBlockWithIfMatch(
+  postId: number,
+  blockIndex: number,
+  attributes: Record<string, unknown>,
+  innerHTML: string,
+  ifMatch: number
+): Promise<{ status: number; data: unknown }> {
+  const credentials = Buffer.from(
+    `${LIVE_ENV.user}:${LIVE_ENV.password}`
+  ).toString('base64');
+
+  const url = `${LIVE_ENV.url.replace(/\/+$/, '')}/wp-json/gk-block-api/v1/posts/${postId}/blocks/${blockIndex}`;
+
+  const response = await axios.patch(
+    url,
+    { attributes, innerHTML, if_match: ifMatch },
+    {
+      headers: {
+        Authorization: `Basic ${credentials}`,
+        'Content-Type': 'application/json',
+      },
+      timeout: 15_000,
+      // Don't throw on 4xx so we can inspect the status.
+      validateStatus: () => true,
+    }
+  );
+  return { status: response.status, data: response.data };
+}
+
+describe.skipIf(skip)('ETag / If-Match concurrency (integration)', () => {
+  it('second write with stale revision_id is rejected with 412 (or plugin does not enforce)', async () => {
+    const client = makeLiveClient();
+
+    await withTestPost(client, async (postId) => {
+      // Step 1: read to get the current revision baseline.
+      const initial = await client.getPageBlocks(postId);
+      const heading = initial.blocks.find((b) => b.name === 'core/heading');
+      expect(heading).toBeDefined();
+      const headingIndex = heading!.index;
+
+      // Step 2: first write — succeeds and bumps the revision.
+      const firstWrite = await client.updateBlock(postId, headingIndex, {
+        attributes: { content: 'First write — takes the slot', level: 2 },
+        innerHTML: '<h2 class="wp-block-heading">First write — takes the slot</h2>',
+      });
+      expect(firstWrite.success).toBe(true);
+      const baseRevision = firstWrite.before_revision_id;
+
+      // Step 3: second write with the ORIGINAL (now-stale) revision_id.
+      const secondWrite = await patchBlockWithIfMatch(
+        postId,
+        headingIndex,
+        { content: 'Second write — should be rejected', level: 2 },
+        '<h2 class="wp-block-heading">Second write — should be rejected</h2>',
+        baseRevision // stale: the first write already consumed this revision
+      );
+
+      if (secondWrite.status === 412) {
+        // Plugin enforces If-Match — verify the error code.
+        const body = secondWrite.data as Record<string, unknown>;
+        expect(body.code).toBe('stale_revision');
+      } else {
+        // Plugin version doesn't enforce if_match yet — acceptable.
+        // We still assert the write didn't crash unexpectedly.
+        expect([200, 201]).toContain(secondWrite.status);
+        console.log(
+          '[integration] if_match not enforced on this plugin build ' +
+          `(got ${secondWrite.status}, expected 412) — stale_revision guard not present`
+        );
+      }
+    });
+  }, 30_000);
+
+  it('write with correct current revision_id succeeds', async () => {
+    const client = makeLiveClient();
+
+    await withTestPost(client, async (postId) => {
+      const initial = await client.getPageBlocks(postId);
+      const heading = initial.blocks.find((b) => b.name === 'core/heading');
+      expect(heading).toBeDefined();
+      const headingIndex = heading!.index;
+
+      // First write — capture its revision_id for use as If-Match.
+      const firstWrite = await client.updateBlock(postId, headingIndex, {
+        attributes: { content: 'Write A', level: 2 },
+        innerHTML: '<h2 class="wp-block-heading">Write A</h2>',
+      });
+      expect(firstWrite.success).toBe(true);
+      const currentRevision = firstWrite.revision_id;
+
+      // Second write passing the CURRENT revision_id — must succeed.
+      const secondWrite = await patchBlockWithIfMatch(
+        postId,
+        headingIndex,
+        { content: 'Write B — with correct If-Match', level: 2 },
+        '<h2 class="wp-block-heading">Write B — with correct If-Match</h2>',
+        currentRevision
+      );
+
+      expect(secondWrite.status).toBe(200);
+      const body = secondWrite.data as Record<string, unknown>;
+      expect(body.success).toBe(true);
+    });
+  }, 30_000);
+});