@gravitykit/block-mcp 2.0.1 → 2.1.0

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

@@ -33,6 +33,27 @@ describe('update_blocks — validation: post_id', () => {
       handleWriteTool('update_blocks', { updates: [{ ref: 'blk_a', innerHTML: 'x' }] }, client as any)
     ).rejects.toThrow('post_id');
   });
+
+  it('rejects a float post_id', async () => {
+    await expect(
+      handleWriteTool('update_blocks', { post_id: 1.5, updates: [{ ref: 'blk_a', innerHTML: 'x' }] }, client as any)
+    ).rejects.toThrow('post_id must be a positive integer');
+  });
+
+  it('rejects a negative post_id', async () => {
+    await expect(
+      handleWriteTool('update_blocks', { post_id: -1, updates: [{ ref: 'blk_a', innerHTML: 'x' }] }, client as any)
+    ).rejects.toThrow('post_id must be a positive integer');
+  });
+
+  it('rejects an overflow post_id', async () => {
+    await expect(
+      handleWriteTool('update_blocks', {
+        post_id: Number.MAX_SAFE_INTEGER + 1,
+        updates: [{ ref: 'blk_a', innerHTML: 'x' }],
+      }, client as any)
+    ).rejects.toThrow('post_id must be a positive integer');
+  });
 });
 
 describe('update_blocks — validation: updates array', () => {

package/src/__tests__/tools/yoast/yoast_get_seo.test.ts

@@ -33,9 +33,17 @@ describe('yoast_get_seo — validation', () => {
     expect(client.getYoastSEO).not.toHaveBeenCalled();
   });
 
-  it('rejects string post_id (must be number)', async () => {
-    await expect(handleYoastTool('yoast_get_seo', { post_id: '42' }, client as any))
-      .rejects.toThrow('post_id');
+  // Coerces a numeric-string post_id (parity with get_post_info / update_post),
+  // rejecting only a genuinely non-numeric value.
+  it('coerces a numeric-string post_id', async () => {
+    client.getYoastSEO.mockResolvedValue(yoastSEOResponse);
+    await handleYoastTool('yoast_get_seo', { post_id: '42' }, client as any);
+    expect(client.getYoastSEO).toHaveBeenCalledWith(42);
+  });
+
+  it('rejects a non-numeric post_id string', async () => {
+    await expect(handleYoastTool('yoast_get_seo', { post_id: 'abc' }, client as any))
+      .rejects.toThrow('post_id must be a positive integer');
     expect(client.getYoastSEO).not.toHaveBeenCalled();
   });
 });

package/src/__tests__/tools/yoast/yoast_update_seo.test.ts

@@ -26,6 +26,22 @@ describe('yoast_update_seo — schema', () => {
     const tool = YOAST_TOOLS.find((t) => t.name === 'yoast_update_seo')!;
     expect(tool.inputSchema.required).toContain('post_id');
   });
+
+  // Regression: some AI clients (e.g. Google Gemini) reject a "null" member in a
+  // JSON Schema `type` array and 400 the entire tools/list request, taking down
+  // every tool on the server. noindex must advertise a single scalar type; the
+  // handler still accepts an explicit null (see "noindex tri-state" tests below).
+  it('advertises noindex as a single boolean type, never a ["boolean","null"] array', () => {
+    const tool = YOAST_TOOLS.find((t) => t.name === 'yoast_update_seo')!;
+    const props = tool.inputSchema.properties as unknown as Record<string, { type?: unknown }>;
+    expect(props.noindex.type).toBe('boolean');
+    // Guard the whole shared field set: no property may use a type array containing "null".
+    for (const [name, schema] of Object.entries(props)) {
+      if (Array.isArray(schema.type)) {
+        expect(schema.type, `${name} uses a type array containing "null"`).not.toContain('null');
+      }
+    }
+  });
 });
 
 describe('yoast_update_seo — validation', () => {

package/src/__tests__/unit/enrichers/cbp-enricher.test.ts

@@ -185,6 +185,27 @@ describe('enrichBlock — Code Block Pro', () => {
     expect(textareaContent).toContain('</textarea>');
   });
 
+  /**
+   * Regression: when the enricher replaces an existing <pre class="shiki"> in
+   * innerHTML, the highlighted codeHTML was passed as the String.replace
+   * REPLACEMENT string, so a `$`-sequence in the source ($$ -> $, $& -> the
+   * whole matched <pre>) was interpreted as a replacement pattern and corrupted
+   * the rendered code. The replacement must be literal.
+   */
+  it('preserves $-sequences in code when replacing existing innerHTML', async () => {
+    const block: BlockDef = {
+      name: 'kevinbatdorf/code-block-pro',
+      attributes: { code: 'A $$MONEY$$ B $& C', language: 'plaintext', copyButton: false },
+      innerHTML: '<div class="wp-block-kevinbatdorf-code-block-pro"><pre class="shiki css-variables"><code>OLD</code></pre></div>',
+    };
+    const result = await enrichBlock(block);
+    expect(result.innerHTML).toContain('$$MONEY$$');
+    // $& would otherwise splice the whole old <pre> back in; the old content
+    // must be gone and the literal $& (shiki escapes the ampersand) preserved.
+    expect(result.innerHTML).not.toContain('OLD');
+    expect(result.innerHTML).toContain('$&#x26;');
+  });
+
   /**
    * Wrapper-style values come straight from caller-supplied attributes. A
    * value containing `"` (whether malicious or just a quoted font-name like

package/src/__tests__/unit/error-translator/translate-wp-error.test.ts

@@ -37,6 +37,17 @@ describe('translateWpError — null contract', () => {
       expect(typeof result, `Expected string translation for "${code}"`).toBe('string');
     }
   });
+
+  it('returns null for codes the plugin never emits (no phantom translations)', () => {
+    // These names look plausible but the PHP plugin does not construct them —
+    // the real codes are post_not_found, invalid_ref, invalid_path. A
+    // translation here would confidently mislead an agent pattern-matching
+    // on `wpCode`.
+    expect(translateWpError('invalid_post_id', { post_id: 7 })).toBeNull();
+    expect(translateWpError('gk_block_api_invalid_ref', { ref: 'blk_x' })).toBeNull();
+    expect(translateWpError('path_not_found', { path: [0] })).toBeNull();
+    expect(translateWpError('path_out_of_bounds', { path: [0] })).toBeNull();
+  });
 });
 
 // ── 2. Per-group describe blocks ─────────────────────────────────────────────
@@ -90,10 +101,10 @@ describe('translateWpError — post lookup', () => {
     expect(msg).toBe('Post not found. List pages with `list_posts` to find the right ID.');
   });
 
-  it('invalid_post_id is an alias of rest_post_invalid_id', () => {
-    const withData = translateWpError('invalid_post_id', { post_id: 7 })!;
+  it('post_not_found — the code the plugin actually emits — embeds post_id', () => {
+    const withData = translateWpError('post_not_found', { post_id: 7 })!;
     expect(withData).toMatch(/Post 7 not found/);
-    const bare = translateWpError('invalid_post_id', null)!;
+    const bare = translateWpError('post_not_found', null)!;
     expect(bare).toMatch(/Post not found/);
   });
 
@@ -107,8 +118,14 @@ describe('translateWpError — post lookup', () => {
 });
 
 describe('translateWpError — block ref / path resolution', () => {
-  it('gk_block_api_invalid_ref embeds ref and post_id', () => {
-    const msg = translateWpError('gk_block_api_invalid_ref', {
+  it('invalid_ref explains the malformed-ref case (empty/non-string ref)', () => {
+    const msg = translateWpError('invalid_ref', null)!;
+    expect(msg).toMatch(/non-empty string/);
+    expect(msg).toMatch(/get_page_blocks/);
+  });
+
+  it('ref_stale embeds ref and post_id and points at get_page_blocks', () => {
+    const msg = translateWpError('ref_stale', {
       ref: 'blk_abc123',
       post_id: 42,
     })!;
@@ -117,40 +134,35 @@ describe('translateWpError — block ref / path resolution', () => {
     expect(msg).toMatch(/get_page_blocks/);
   });
 
-  it('gk_block_api_invalid_ref uses ? placeholders when data is null', () => {
-    const msg = translateWpError('gk_block_api_invalid_ref', null)!;
+  it('ref_stale uses ? placeholder and drops the post clause when data is null', () => {
+    const msg = translateWpError('ref_stale', null)!;
     expect(msg).toMatch(/Block ref `\?`/);
-    expect(msg).toMatch(/post \?/);
+    expect(msg).not.toMatch(/ in post/);
   });
 
-  it('invalid_ref is an alias', () => {
-    const msg = translateWpError('invalid_ref', { ref: 'blk_xyz', post_id: 5 })!;
-    expect(msg).toContain('blk_xyz');
-  });
-
-  it('path_not_found formats path array correctly', () => {
-    const msg = translateWpError('path_not_found', { path: [0, 2, 1] })!;
+  it('invalid_path formats the path array and mentions re-fetching', () => {
+    const msg = translateWpError('invalid_path', { path: [0, 2, 1] })!;
     expect(msg).toMatch(/\[0, 2, 1\]/);
     expect(msg).toMatch(/Re-fetch the post/);
   });
 
-  it('path_not_found uses ? when path is absent', () => {
-    expect(translateWpError('path_not_found', null)).toMatch(/path \? doesn't address/);
+  it('invalid_path uses ? when path is absent', () => {
+    expect(translateWpError('invalid_path', null)).toMatch(/path \? doesn't address/);
   });
 
-  it('invalid_path is an alias', () => {
-    const msg = translateWpError('invalid_path', { path: [1] })!;
-    expect(msg).toMatch(/\[1\]/);
+  it('invalid_index embeds flat_index and mentions re-fetching', () => {
+    const msg = translateWpError('invalid_index', { flat_index: 12 })!;
+    expect(msg).toMatch(/Block index 12 out of range/);
+    expect(msg).toMatch(/get_page_blocks/);
   });
 
-  it('path_out_of_bounds mentions re-fetching', () => {
-    const msg = translateWpError('path_out_of_bounds', { path: [99] })!;
-    expect(msg).toMatch(/out of bounds/);
-    expect(msg).toMatch(/get_page_blocks/);
+  it('invalid_index survives a missing flat_index hint', () => {
+    const msg = translateWpError('invalid_index', null)!;
+    expect(msg).toMatch(/^Block index out of range/);
   });
 });
 
-describe('translateWpError — preference enforcement', () => {
+describe('translateWpError — preference / storage enforcement', () => {
   it('legacy_block embeds block name and replacement', () => {
     const msg = translateWpError('legacy_block', {
       block: 'example/heading',
@@ -207,6 +219,47 @@ describe('translateWpError — preference enforcement', () => {
     expect(msg).toMatch(/innerHTML/);
     expect(msg).toMatch(/static block/);
   });
+
+  it('dual_storage_requires_both names the block and tells the agent to send both fields', () => {
+    const msg = translateWpError('dual_storage_requires_both', { block_name: 'yoast/faq-block' })!;
+    expect(msg).toMatch(/yoast\/faq-block is dual-storage/);
+    expect(msg).toMatch(/attributes.*innerHTML.*together/);
+  });
+
+  it('dual_storage_requires_both falls back gracefully without a block name', () => {
+    const msg = translateWpError('dual_storage_requires_both', null)!;
+    expect(msg).toMatch(/This block is dual-storage/);
+  });
+
+  it('block_depth_exceeded embeds max/actual depth when present', () => {
+    const msg = translateWpError('block_depth_exceeded', { max_depth: 32, actual_depth: 33 })!;
+    expect(msg).toMatch(/max 32, got 33/);
+    expect(msg).toMatch(/nesting depth/);
+  });
+
+  it('block_depth_exceeded survives missing depth hints', () => {
+    const msg = translateWpError('block_depth_exceeded', null)!;
+    expect(msg).toMatch(/^Block tree exceeds the maximum nesting depth/);
+  });
+});
+
+describe('translateWpError — concurrency / staleness', () => {
+  it('edit_conflict tells the agent to re-fetch and retry', () => {
+    const msg = translateWpError('edit_conflict', null)!;
+    expect(msg).toMatch(/changed since it was read/);
+    expect(msg).toMatch(/get_page_blocks/);
+  });
+
+  it('stale_revision embeds the current revision when present', () => {
+    const msg = translateWpError('stale_revision', { current_revision: 88 })!;
+    expect(msg).toMatch(/current revision: 88/);
+    expect(msg).toMatch(/get_page_blocks/);
+  });
+
+  it('stale_revision survives a missing current_revision hint', () => {
+    const msg = translateWpError('stale_revision', null)!;
+    expect(msg).toMatch(/^The post has changed since you fetched it\. Re-fetch/);
+  });
 });
 
 describe('translateWpError — rate limiting', () => {
@@ -221,6 +274,18 @@ describe('translateWpError — rate limiting', () => {
     expect(msg).toMatch(/^Too many writes in the last minute/);
     expect(msg).not.toMatch(/on post/);
   });
+
+  it('rate_limit_locked advises a brief retry and embeds post_id', () => {
+    const msg = translateWpError('rate_limit_locked', { post_id: 7 })!;
+    expect(msg).toMatch(/on post 7/);
+    expect(msg).toMatch(/Retry in a moment/);
+  });
+
+  it('rate_limit_locked drops post_id clause when absent', () => {
+    const msg = translateWpError('rate_limit_locked', null)!;
+    expect(msg).toMatch(/^Another write is in progress/);
+    expect(msg).not.toMatch(/on post/);
+  });
 });
 
 describe('translateWpError — v1.2 post lifecycle', () => {
@@ -239,6 +304,12 @@ describe('translateWpError — v1.2 post lifecycle', () => {
     const msg = translateWpError('invalid_status', null)!;
     expect(msg).toMatch(/draft/);
   });
+
+  it('trash_disabled points at the site setting', () => {
+    const msg = translateWpError('trash_disabled', null)!;
+    expect(msg).toMatch(/trash is turned off/);
+    expect(msg).toMatch(/Settings/);
+  });
 });
 
 describe('translateWpError — media uploads', () => {
@@ -286,19 +357,19 @@ describe('translateWpError — full error-code coverage matrix', () => {
 describe('translateWpError — data extraction edge cases', () => {
   it('ignores non-object data payload', () => {
     // String data: should not throw, fall back to ? placeholders
-    expect(() => translateWpError('gk_block_api_invalid_ref', 'oops')).not.toThrow();
+    expect(() => translateWpError('ref_stale', 'oops')).not.toThrow();
   });
 
   it('ignores array data payload', () => {
-    expect(() => translateWpError('gk_block_api_invalid_ref', [1, 2, 3])).not.toThrow();
+    expect(() => translateWpError('ref_stale', [1, 2, 3])).not.toThrow();
   });
 
   it('handles path array with non-integer values — does not throw', () => {
     // extractHints validates each element is a finite number; non-integers
     // are filtered out, so the path hint falls back to ? placeholder.
     // The translator must not throw regardless of payload shape.
-    expect(() => translateWpError('path_not_found', { path: ['a', 'b'] })).not.toThrow();
-    const msg = translateWpError('path_not_found', { path: ['a', 'b'] });
+    expect(() => translateWpError('invalid_path', { path: ['a', 'b'] })).not.toThrow();
+    const msg = translateWpError('invalid_path', { path: ['a', 'b'] });
     expect(msg).not.toBeNull();
   });
 

package/src/__tests__/unit/instructions.test.ts

@@ -202,19 +202,19 @@ describe('fetchAddendum', () => {
     expect(result).toBe('hi');
   });
 
-  it('issues GET to /wp-json/gk-block-api/v1/instructions', async () => {
+  it('issues GET on the permalink-independent ?rest_route= form', async () => {
     vi.mocked(axios.get).mockResolvedValueOnce({ data: { addendum: 'use info callout' } });
     await fetchAddendum('https://example.com');
     expect(vi.mocked(axios.get)).toHaveBeenCalledOnce();
     const [url] = vi.mocked(axios.get).mock.calls[0]!;
-    expect(url).toBe('https://example.com/wp-json/gk-block-api/v1/instructions');
+    expect(url).toBe('https://example.com/?rest_route=/gk-block-api/v1/instructions');
   });
 
   it('normalizes trailing slashes in the base URL', async () => {
     vi.mocked(axios.get).mockResolvedValueOnce({ data: { addendum: 'x' } });
     await fetchAddendum('https://example.com///');
     const [url] = vi.mocked(axios.get).mock.calls[0]!;
-    expect(url).toBe('https://example.com/wp-json/gk-block-api/v1/instructions');
+    expect(url).toBe('https://example.com/?rest_route=/gk-block-api/v1/instructions');
   });
 
   it('passes a short timeout and JSON Accept header', async () => {

package/src/__tests__/unit/preferences/enrich-pattern-list.test.ts

@@ -17,7 +17,7 @@ function makePattern(overrides: Partial<Pattern> & { id: number; name: string })
     created: '2026-01-01',
     modified: '2026-01-01',
     reference_count: 0,
-    preference: { score: 80, tier: 'recommended', reasons: [] },
+    preference: { score: 80, tier: 'preferred', reasons: [] },
     contains_blocks: [],
     has_legacy_blocks: false,
     ...overrides,
@@ -49,12 +49,28 @@ describe('enrichPatternList — empty input', () => {
   });
 });
 
+describe('enrichPatternList — tier buckets match the tiers the server emits', () => {
+  it('lists preferred and acceptable patterns instead of reporting none', () => {
+    // The server emits preferred/acceptable/avoid/legacy — never "recommended".
+    // Filtering the usable bucket on a non-existent tier hid every pattern.
+    const patterns = [
+      makePattern({ id: 1, name: 'Hero', preference: { score: 90, tier: 'preferred', reasons: [] } }),
+      makePattern({ id: 2, name: 'Card', preference: { score: 60, tier: 'acceptable', reasons: [] } }),
+    ];
+    const { summary } = enrichPatternList(patterns);
+    expect(summary).toContain('RECOMMENDED patterns');
+    expect(summary).toContain('Hero');
+    expect(summary).toContain('Card');
+    expect(summary).not.toMatch(/No patterns found/);
+  });
+});
+
 describe('enrichPatternList — sorting', () => {
   it('sorts by score descending', () => {
     const patterns = [
       makePattern({ id: 1, name: 'Low',  preference: { score: 10, tier: 'avoid',       reasons: [] } }),
-      makePattern({ id: 2, name: 'High', preference: { score: 95, tier: 'recommended', reasons: [] } }),
-      makePattern({ id: 3, name: 'Mid',  preference: { score: 50, tier: 'recommended', reasons: [] } }),
+      makePattern({ id: 2, name: 'High', preference: { score: 95, tier: 'preferred', reasons: [] } }),
+      makePattern({ id: 3, name: 'Mid',  preference: { score: 50, tier: 'preferred', reasons: [] } }),
     ];
     const result = enrichPatternList(patterns);
     expect(result.patterns[0].name).toBe('High');
@@ -64,8 +80,8 @@ describe('enrichPatternList — sorting', () => {
 
   it('preserves equal-score order (stable sort is not required, just non-crash)', () => {
     const patterns = [
-      makePattern({ id: 1, name: 'A', preference: { score: 80, tier: 'recommended', reasons: [] } }),
-      makePattern({ id: 2, name: 'B', preference: { score: 80, tier: 'recommended', reasons: [] } }),
+      makePattern({ id: 1, name: 'A', preference: { score: 80, tier: 'preferred', reasons: [] } }),
+      makePattern({ id: 2, name: 'B', preference: { score: 80, tier: 'preferred', reasons: [] } }),
     ];
     const result = enrichPatternList(patterns);
     expect(result.patterns).toHaveLength(2);
@@ -74,7 +90,7 @@ describe('enrichPatternList — sorting', () => {
   it('does not mutate the input array', () => {
     const patterns = [
       makePattern({ id: 1, name: 'A', preference: { score: 10, tier: 'avoid',       reasons: [] } }),
-      makePattern({ id: 2, name: 'B', preference: { score: 95, tier: 'recommended', reasons: [] } }),
+      makePattern({ id: 2, name: 'B', preference: { score: 95, tier: 'preferred', reasons: [] } }),
     ];
     const original = [...patterns];
     enrichPatternList(patterns);
@@ -85,7 +101,7 @@ describe('enrichPatternList — sorting', () => {
 describe('enrichPatternList — summary generation', () => {
   it('includes RECOMMENDED label for recommended patterns', () => {
     const patterns = [
-      makePattern({ id: 1, name: 'Hero', preference: { score: 85, tier: 'recommended', reasons: [] } }),
+      makePattern({ id: 1, name: 'Hero', preference: { score: 85, tier: 'preferred', reasons: [] } }),
     ];
     const result = enrichPatternList(patterns);
     expect(result.summary).toMatch(/RECOMMENDED/);
@@ -121,14 +137,14 @@ describe('enrichPatternList — summary generation', () => {
 
   it('does not include AVOID label when all patterns are recommended', () => {
     const patterns = [
-      makePattern({ id: 1, name: 'Good', preference: { score: 80, tier: 'recommended', reasons: [] } }),
+      makePattern({ id: 1, name: 'Good', preference: { score: 80, tier: 'preferred', reasons: [] } }),
     ];
     expect(enrichPatternList(patterns).summary).not.toMatch(/AVOID/);
   });
 
   it('shows both sections when mixed tiers', () => {
     const patterns = [
-      makePattern({ id: 1, name: 'Good',  preference: { score: 80, tier: 'recommended', reasons: [] } }),
+      makePattern({ id: 1, name: 'Good',  preference: { score: 80, tier: 'preferred', reasons: [] } }),
       makePattern({ id: 2, name: 'Bad',   preference: { score: 0,  tier: 'legacy',      reasons: [] }, has_legacy_blocks: true }),
     ];
     const { summary } = enrichPatternList(patterns);
@@ -140,7 +156,7 @@ describe('enrichPatternList — summary generation', () => {
     const patterns = [
       makePattern({
         id: 1, name: 'Hero',
-        preference: { score: 80, tier: 'recommended', reasons: [] },
+        preference: { score: 80, tier: 'preferred', reasons: [] },
         contains_blocks: ['core/heading', 'core/paragraph', 'core/image'],
       }),
     ];

package/src/__tests__/unit/rest-url.test.ts

@@ -0,0 +1,23 @@
+import { describe, it, expect } from 'vitest';
+import { restRouteUrl } from '../../rest-url.js';
+
+// The client and the instructions fetch must reach WordPress on the
+// permalink-independent ?rest_route= form. Hardcoding /wp-json/ let the
+// connector succeed and then every tool call 404 on plain-permalink sites.
+describe('restRouteUrl', () => {
+  it('uses the ?rest_route= form, never a hardcoded /wp-json/ path', () => {
+    expect(restRouteUrl('https://site.test')).toBe('https://site.test/?rest_route=/gk-block-api/v1');
+    expect(restRouteUrl('https://site.test')).not.toContain('/wp-json/');
+  });
+
+  it('trims trailing slashes on the site URL', () => {
+    expect(restRouteUrl('https://site.test/')).toBe('https://site.test/?rest_route=/gk-block-api/v1');
+    expect(restRouteUrl('https://site.test///')).toBe('https://site.test/?rest_route=/gk-block-api/v1');
+  });
+
+  it('appends a route suffix after the namespace', () => {
+    expect(restRouteUrl('https://site.test', '/instructions')).toBe(
+      'https://site.test/?rest_route=/gk-block-api/v1/instructions'
+    );
+  });
+});