@gravitykit/block-mcp 2.0.0-beta → 2.1.0

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 ─────────────────────────────────────────────
@@ -44,7 +55,7 @@ describe('translateWpError — null contract', () => {
 describe('translateWpError — routing & auth', () => {
   it('rest_no_route mentions the plugin name', () => {
     const msg = translateWpError('rest_no_route', null)!;
-    expect(msg).toMatch(/gk-block-api/);
+    expect(msg).toMatch(/Block MCP/);
     expect(msg).toMatch(/WORDPRESS_URL/);
   });
 
@@ -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'
+    );
+  });
+});

package/src/agent-guide.ts

@@ -0,0 +1,85 @@
+/**
+ * The agent-guide resource content (block-mcp://agent-guide).
+ *
+ * Workflow guidance served to MCP clients as a resource and prompt seed.
+ * Lives in its own module (not index.ts, which boots the server on import)
+ * so the discoverability contract is testable: everything an agent needs to
+ * author content — including container nesting — must be learnable from the
+ * tool surface + this guide, never from reading this repo's source.
+ */
+
+export const AGENT_GUIDE_CONTENT = `# Block MCP — Agent Guide
+
+## URL → post ID resolution
+
+NEVER run curl, wget, or any bash/shell command to hit wp-json or resolve a URL to a post ID.
+The MCP does this for you:
+
+- \`get_page_blocks\` accepts \`url\` as an alternative to \`post_id\`. Pass the full URL or path; the server resolves it via \`url_to_postid\`.
+- For explicit resolution (title, post_type, edit_url before editing), call \`resolve_url\`.
+
+If the user says "change X on https://example.com/some-page/", your first tool call should be \`get_page_blocks({ url: "...", search: "keyword" })\` or \`resolve_url({ url: "..." })\` — not a shell command.
+
+## Moving / reordering blocks
+
+NEVER do a move as separate \`insert_blocks\` + \`delete_block\` calls — if the delete is skipped or fails, the page ends up with an orphaned clone of the original. The atomic primitive is the \`move\` op on \`edit_block_tree\`:
+
+- Target the source with \`ref\` (the \`gk_ref\` from \`get_page_blocks\`) or \`path\`. Prefer \`ref\` — it survives sibling shifts; paths go stale the moment any earlier block is inserted or removed.
+- Express the destination with \`destination_ref\` or \`destination\` (path). For path destinations, use **pre-move** indexing — write the path as if the source were still in place; the server adjusts indices after the removal.
+- Use \`count\` to move N consecutive siblings in a single op.
+- The server rejects moves into the source itself or any of its descendants.
+- The whole \`edit_block_tree\` call is one revision, reversible via \`revert_to_revision\`.
+
+If you must fall back to the flat-index tools, do \`insert_blocks\` + \`delete_block\` in the same turn and re-fetch \`get_page_blocks\` afterward to confirm exactly one copy remains.
+
+## Building container blocks (groups, columns, callouts)
+
+Every block def accepted by \`insert_blocks\`, \`replace_block_range\`, and \`rewrite_post_blocks\` nests recursively via \`innerBlocks\` — build a whole container (and its children) in ONE call instead of inserting pieces and moving them around.
+
+- The container's \`innerHTML\` is its wrapper element only — an empty wrapper; children render inside it. E.g. \`core/group\` → \`<div class="wp-block-group"></div>\`, \`core/list\` → \`<ul class="wp-block-list"></ul>\`.
+- Each entry in \`innerBlocks\` is a full block def and may nest further (columns → column → content).
+- Include any style class in BOTH the \`className\` attribute and the wrapper \`innerHTML\`.
+
+Example — a styled callout (a \`core/group\` wrapping a paragraph):
+
+\`\`\`json
+{
+  "name": "core/group",
+  "attributes": { "className": "is-style-callout-info", "layout": { "type": "constrained" } },
+  "innerHTML": "<div class=\\"wp-block-group is-style-callout-info\\"></div>",
+  "innerBlocks": [
+    { "name": "core/paragraph", "innerHTML": "<p>Tip text here.</p>" }
+  ]
+}
+\`\`\`
+
+Site-specific style conventions (e.g. callout class names) come from this site's instructions addendum — prefer those over inventing classes.
+
+## Verifying writes
+
+Every write echoes the canonical post-save snapshot. Use it. Do not fetch the public page to verify what saved.
+
+- \`update_block\` always returns \`saved.inner_html\` + \`saved.attributes\` — the exact content that just landed in post_content. The write call IS the verification round-trip.
+- \`update_blocks\` returns per-result \`saved\` only when called with \`verbose: true\` (default false to keep batch responses compact). Pass \`verbose: true\` if you need to confirm each item without a re-read.
+- For after-the-fact re-reads of a single known block, use \`get_block({ post_id, ref })\` — returns the same \`saved\` shape, lighter than \`get_page_blocks\`.
+
+For dynamic blocks (\`saved.is_dynamic: true\`, e.g. shortcodes, query loops, latest-posts), \`saved.inner_html\` is the stored template that runs at render time — not the rendered HTML the visitor sees. That's expected; the canonical state is the template.
+
+## Block preferences (site-defined)
+
+Block preference policy is configured per-site in the WordPress admin (the
+gk-block-api Preferences option) and exposed dynamically. There is no
+client-side hardcoded list of "good" vs "bad" namespaces.
+
+How to discover the policy at runtime:
+
+1. \`list_block_types\` returns blocks grouped by tier (PREFERRED / ACCEPTABLE / AVOID / LEGACY) for the current site. Use this when you need the full picture.
+2. \`get_page_blocks\` annotates non-preferred blocks inline with \`preference.tier\` and (when configured) \`preference.suggested_replacement\`. Trust those fields — they reflect the live config.
+3. \`insert_blocks\` rejects legacy-tier blocks with a \`legacy_block\` error that includes the rejected namespace, the suggested replacement, and a pointer back to this resource.
+
+How to behave:
+
+- Prefer the highest-tier blocks for new content. Defer to the server's classification rather than guessing from a namespace prefix.
+- Reuse existing patterns before building from scratch — call \`list_patterns\` first.
+- For patterns that need per-page customization, use \`synced: false\` to inline them.
+- When you encounter legacy blocks on a page during a read, note them but do not replace unless asked.`;