@gravitykit/block-mcp 2.0.0-beta

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

@@ -0,0 +1,318 @@
+/**
+ * Unit tests for translateWpError() — the WP REST error → agent-hint translator.
+ *
+ * Structure:
+ *   1. Null-return contract (unknown / undefined codes)
+ *   2. Per-group describe blocks (mirrors the switch in error-translator.ts)
+ *   3. it.each coverage matrix over every documented error code
+ *
+ * The coverage matrix is the key regression guard: any new code added to the
+ * README Error Codes table should appear in error-envelopes.ts and get caught
+ * here automatically if it's also added to the translator switch.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { translateWpError } from '../../../error-translator.js';
+import { ERROR_ENVELOPES, TRANSLATED_CODES } from '../../fixtures/error-envelopes.js';
+
+// ── 1. Null-return contract ──────────────────────────────────────────────────
+
+describe('translateWpError — null contract', () => {
+  it('returns null for an unknown code', () => {
+    expect(translateWpError('something_totally_unknown_xyz', null)).toBeNull();
+  });
+
+  it('returns null for undefined code', () => {
+    expect(translateWpError(undefined, null)).toBeNull();
+  });
+
+  it('returns null for empty string code', () => {
+    expect(translateWpError('', null)).toBeNull();
+  });
+
+  it('returns a non-null string for every code in TRANSLATED_CODES', () => {
+    for (const code of TRANSLATED_CODES) {
+      const result = translateWpError(code, null);
+      expect(result, `Expected a translation for "${code}"`).not.toBeNull();
+      expect(typeof result, `Expected string translation for "${code}"`).toBe('string');
+    }
+  });
+});
+
+// ── 2. Per-group describe blocks ─────────────────────────────────────────────
+
+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(/WORDPRESS_URL/);
+  });
+
+  it('rest_forbidden mentions Application Password and capability', () => {
+    const msg = translateWpError('rest_forbidden', null)!;
+    expect(msg).toMatch(/Permission denied/);
+    expect(msg).toMatch(/Application Password/);
+    expect(msg).toMatch(/edit_posts/);
+  });
+
+  it('rest_cannot_edit mentions capability', () => {
+    const msg = translateWpError('rest_cannot_edit', null)!;
+    expect(msg).toMatch(/Permission denied/);
+  });
+
+  it('rest_cannot_create mentions capability', () => {
+    const msg = translateWpError('rest_cannot_create', null)!;
+    expect(msg).toMatch(/Permission denied/);
+  });
+
+  it('rest_cookie_invalid_nonce mentions both env vars', () => {
+    const msg = translateWpError('rest_cookie_invalid_nonce', null)!;
+    expect(msg).toMatch(/WORDPRESS_USER/);
+    expect(msg).toMatch(/WORDPRESS_APP_PASSWORD/);
+  });
+
+  it('rest_authentication_required mentions both env vars', () => {
+    const msg = translateWpError('rest_authentication_required', null)!;
+    expect(msg).toMatch(/WORDPRESS_USER/);
+    expect(msg).toMatch(/WORDPRESS_APP_PASSWORD/);
+  });
+});
+
+describe('translateWpError — post lookup', () => {
+  it('rest_post_invalid_id embeds post_id from data', () => {
+    const msg = translateWpError('rest_post_invalid_id', { post_id: 1234 })!;
+    expect(msg).toMatch(/Post 1234 not found/);
+    expect(msg).toMatch(/list_posts/);
+  });
+
+  it('rest_post_invalid_id gracefully omits id when data is null', () => {
+    const msg = translateWpError('rest_post_invalid_id', null)!;
+    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 })!;
+    expect(withData).toMatch(/Post 7 not found/);
+    const bare = translateWpError('invalid_post_id', null)!;
+    expect(bare).toMatch(/Post not found/);
+  });
+
+  it('not_found with post_id mentions the id', () => {
+    expect(translateWpError('not_found', { post_id: 9 })).toMatch(/Post 9 not found/);
+  });
+
+  it('not_found without post_id gives generic message', () => {
+    expect(translateWpError('not_found', null)).toMatch(/Resource not found/);
+  });
+});
+
+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', {
+      ref: 'blk_abc123',
+      post_id: 42,
+    })!;
+    expect(msg).toContain('blk_abc123');
+    expect(msg).toContain('post 42');
+    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)!;
+    expect(msg).toMatch(/Block ref `\?`/);
+    expect(msg).toMatch(/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] })!;
+    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 is an alias', () => {
+    const msg = translateWpError('invalid_path', { path: [1] })!;
+    expect(msg).toMatch(/\[1\]/);
+  });
+
+  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/);
+  });
+});
+
+describe('translateWpError — preference enforcement', () => {
+  it('legacy_block embeds block name and replacement', () => {
+    const msg = translateWpError('legacy_block', {
+      block: 'example/heading',
+      suggested_replacement: 'core/heading',
+    })!;
+    expect(msg).toMatch(/example\/heading is in a namespace this site has configured as legacy/);
+    expect(msg).toMatch(/core\/heading/);
+  });
+
+  it('legacy_block accepts block_name as alternative to block', () => {
+    const msg = translateWpError('legacy_block', { block_name: 'example/text' })!;
+    expect(msg).toMatch(/example\/text is in a namespace this site has configured as legacy/);
+  });
+
+  it('legacy_block falls back to generic when no block name', () => {
+    expect(translateWpError('legacy_block', null)).toMatch(/Legacy block rejected/);
+  });
+
+  it('legacy_block message does not name specific third-party vendors', () => {
+    // Sanity check: the message must stay vendor-agnostic — naming specific
+    // namespaces (stackable / ugb / jetpack) makes the message brittle when
+    // site preferences change and singles out individual plugins.
+    const msg = translateWpError('legacy_block', { block: 'example/x' })!;
+    expect(msg).not.toMatch(/Stackable|UGB|Jetpack/i);
+  });
+
+  it('inner_html_required names the offending attributes and the block', () => {
+    const msg = translateWpError('inner_html_required', {
+      block: 'core/paragraph',
+      source_bound_attributes: ['content'],
+    })!;
+    expect(msg).toMatch(/core\/paragraph/);
+    expect(msg).toMatch(/\[content\]/);
+    expect(msg).toMatch(/innerHTML/);
+    expect(msg).toMatch(/invalid content/);
+  });
+
+  it('inner_html_required falls back gracefully without block name', () => {
+    const msg = translateWpError('inner_html_required', {
+      source_bound_attributes: ['url'],
+    })!;
+    expect(msg).toMatch(/\[url\]/);
+    expect(msg).toMatch(/innerHTML/);
+  });
+
+  it('inner_html_required survives missing source_bound_attributes hint', () => {
+    const msg = translateWpError('inner_html_required', { block: 'core/heading' })!;
+    expect(msg).toMatch(/core\/heading/);
+    expect(msg).toMatch(/innerHTML/);
+  });
+
+  it('static_markup_stale_risk mentions innerHTML and static block', () => {
+    const msg = translateWpError('static_markup_stale_risk', null)!;
+    expect(msg).toMatch(/innerHTML/);
+    expect(msg).toMatch(/static block/);
+  });
+});
+
+describe('translateWpError — rate limiting', () => {
+  it('rate_limit_exceeded embeds post_id when present', () => {
+    const msg = translateWpError('rate_limit_exceeded', { post_id: 7 })!;
+    expect(msg).toMatch(/on post 7 in the last minute/);
+    expect(msg).toMatch(/edit_block_tree/);
+  });
+
+  it('rate_limit_exceeded drops post_id clause when absent', () => {
+    const msg = translateWpError('rate_limit_exceeded', null)!;
+    expect(msg).toMatch(/^Too many writes in the last minute/);
+    expect(msg).not.toMatch(/on post/);
+  });
+});
+
+describe('translateWpError — v1.2 post lifecycle', () => {
+  it('mixed_trash_payload suggests separate calls', () => {
+    const msg = translateWpError('mixed_trash_payload', null)!;
+    expect(msg).toMatch(/Trash the post in one call/);
+  });
+
+  it('invalid_post_type mentions the allowlist option', () => {
+    expect(translateWpError('invalid_post_type', null)).toMatch(
+      /gk_block_api_post_types_allowlist/
+    );
+  });
+
+  it('invalid_status lists valid values', () => {
+    const msg = translateWpError('invalid_status', null)!;
+    expect(msg).toMatch(/draft/);
+  });
+});
+
+describe('translateWpError — media uploads', () => {
+  it('invalid_url mentions SSRF guard', () => {
+    expect(translateWpError('invalid_url', null)).toMatch(/SSRF guard/);
+  });
+
+  it('disallowed_mime suggests image formats', () => {
+    expect(translateWpError('disallowed_mime', null)).toMatch(/PNG\/JPG\/WEBP/);
+  });
+});
+
+// ── 3. Coverage matrix over all documented error codes ───────────────────────
+//
+// For every code in ERROR_ENVELOPES, assert:
+//   a) translateWpError returns a string (if code is in TRANSLATED_CODES)
+//   b) or returns null (if code is unknown to the translator)
+//
+// This makes it impossible to add a new documented code without the test
+// suite visibly reporting a gap.
+
+describe('translateWpError — full error-code coverage matrix', () => {
+  it.each(
+    ERROR_ENVELOPES.map((e) => [e.code, e.data, TRANSLATED_CODES.has(e.code)] as const)
+  )('code=%s — returns %s', (code, data, isTranslated) => {
+    const result = translateWpError(code, data);
+    if (isTranslated) {
+      expect(result, `Expected a translation for "${code}"`).not.toBeNull();
+      expect(typeof result).toBe('string');
+      // Every translated message should be non-empty and end without extra whitespace
+      expect((result as string).trim().length).toBeGreaterThan(10);
+    } else {
+      // Undocumented / not yet translated — must return null, not throw.
+      // Asserting the return value (not just the absence of a throw) catches
+      // the case where a future change adds a fallback that returns a
+      // generic string for unknown codes — silently translating unknowns is
+      // worse than letting them surface raw.
+      expect(result, `Expected null for untranslated code "${code}"`).toBeNull();
+    }
+  });
+});
+
+// ── 4. extractHints edge cases ────────────────────────────────────────────────
+
+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();
+  });
+
+  it('ignores array data payload', () => {
+    expect(() => translateWpError('gk_block_api_invalid_ref', [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(msg).not.toBeNull();
+  });
+
+  it('block_name field is used when block field is absent', () => {
+    const msg = translateWpError('legacy_block', { block_name: 'example/icon' })!;
+    expect(msg).toContain('example/icon');
+  });
+
+  it('block field takes precedence over block_name when both present', () => {
+    const msg = translateWpError('legacy_block', {
+      block: 'example/text',
+      block_name: 'other/block',
+    })!;
+    expect(msg).toContain('example/text');
+    expect(msg).not.toContain('other/block');
+  });
+});

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

@@ -0,0 +1,374 @@
+/**
+ * Unit tests for src/instructions.ts (BLOCK-19).
+ *
+ * Covers the three pure helpers (sanitizeAddendum, combineInstructions,
+ * BASELINE) plus the network-bound fetchAddendum / getInstructions
+ * helpers with axios mocked. No live HTTP — these all run offline.
+ *
+ * Invariants pinned here:
+ *   - Sanitize strips C0 + DEL + Bidi/zero-width without touching tab/LF/CR.
+ *   - Sanitize truncates at MAX_ADDENDUM_LENGTH (defense in depth).
+ *   - Sanitize coerces non-string input to '' (no exceptions thrown).
+ *   - Combine returns baseline unchanged when addendum empty.
+ *   - Combine joins with `\n\n` when addendum non-empty.
+ *   - fetchAddendum honors BLOCK_MCP_INSTRUCTIONS_OFF=1 and skips the call.
+ *   - fetchAddendum falls back to '' on network failure (no throw).
+ *   - fetchAddendum sanitizes the remote payload (defense in depth).
+ *   - getInstructions wraps fetch + combine for the public entry point.
+ */
+
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import axios from 'axios';
+
+vi.mock('axios');
+
+import {
+  BASELINE,
+  MAX_ADDENDUM_LENGTH,
+  combineInstructions,
+  fetchAddendum,
+  getInstructions,
+  sanitizeAddendum,
+} from '../../instructions.js';
+
+const ORIG_ENV = { ...process.env };
+
+beforeEach(() => {
+  // Each test starts with a clean env to keep BLOCK_MCP_INSTRUCTIONS_OFF
+  // assertions isolated. Vitest doesn't reset process.env between tests
+  // on its own.
+  process.env = { ...ORIG_ENV };
+  vi.clearAllMocks();
+});
+
+afterEach(() => {
+  process.env = { ...ORIG_ENV };
+});
+
+// ── BASELINE ─────────────────────────────────────────────────────────────────
+
+describe('BASELINE', () => {
+  /**
+   * The baseline string is the contract the SDK and every client depend
+   * on. Pinning its length guards against accidental edits that strip
+   * crucial guidance — e.g. a refactor that drops the "saved.inner_html
+   * is the canonical post-save snapshot" rule would degrade every
+   * client. If this assertion fails, you either intentionally rewrote
+   * the baseline (update the bound) or accidentally truncated it.
+   */
+  it('is a non-trivial, non-empty string', () => {
+    expect(typeof BASELINE).toBe('string');
+    expect(BASELINE.length).toBeGreaterThan(200);
+  });
+
+  it('mentions saved.inner_html guidance', () => {
+    expect(BASELINE).toContain('saved.inner_html');
+  });
+
+  it('mentions URL → post_id resolution rule', () => {
+    expect(BASELINE).toContain('post_id is resolved server-side');
+  });
+});
+
+// ── sanitizeAddendum ─────────────────────────────────────────────────────────
+
+describe('sanitizeAddendum', () => {
+  it('returns empty string for non-string input', () => {
+    expect(sanitizeAddendum(undefined)).toBe('');
+    expect(sanitizeAddendum(null)).toBe('');
+    expect(sanitizeAddendum(42)).toBe('');
+    expect(sanitizeAddendum({ a: 1 })).toBe('');
+    expect(sanitizeAddendum([])).toBe('');
+  });
+
+  it('passes plain ASCII through unchanged', () => {
+    expect(sanitizeAddendum('Use callouts for tips.')).toBe('Use callouts for tips.');
+  });
+
+  it('preserves newlines, tabs, and indented bullets', () => {
+    const v = '- Top\n\t- Nested\n- Bottom';
+    expect(sanitizeAddendum(v)).toBe(v);
+  });
+
+  it('strips ASCII C0 control characters except tab/LF/CR', () => {
+    const v = 'A\x00B\x07C\x1BD\x08E';
+    expect(sanitizeAddendum(v)).toBe('ABCDE');
+  });
+
+  it('strips DEL character (0x7F)', () => {
+    expect(sanitizeAddendum('foo\x7Fbar')).toBe('foobar');
+  });
+
+  it('strips Bidi override codepoints', () => {
+    // U+202E RIGHT-TO-LEFT OVERRIDE — classic spoofing vector. The
+    // expected output is the visible text only, with the override gone.
+    const v = 'allow‮gnirts‬';
+    const cleaned = sanitizeAddendum(v);
+    expect(cleaned).not.toContain('‮');
+    expect(cleaned).not.toContain('‬');
+    expect(cleaned).toContain('allow');
+  });
+
+  it('strips zero-width characters', () => {
+    // ZWSP (U+200B), ZWNJ (U+200C), ZWJ (U+200D), BOM (U+FEFF).
+    const v = 'visi​ble‌‍ text';
+    expect(sanitizeAddendum(v)).toBe('visible text');
+  });
+
+  it('normalizes CRLF and CR to LF', () => {
+    expect(sanitizeAddendum('a\r\nb\rc')).toBe('a\nb\nc');
+  });
+
+  it('trims outer whitespace', () => {
+    expect(sanitizeAddendum('\n\n  inner content  \n')).toBe('inner content');
+  });
+
+  it('truncates to MAX_ADDENDUM_LENGTH', () => {
+    const long = 'A'.repeat(MAX_ADDENDUM_LENGTH + 500);
+    expect(sanitizeAddendum(long)).toHaveLength(MAX_ADDENDUM_LENGTH);
+  });
+
+  it('accepts an input exactly at the cap', () => {
+    const exact = 'B'.repeat(MAX_ADDENDUM_LENGTH);
+    expect(sanitizeAddendum(exact)).toHaveLength(MAX_ADDENDUM_LENGTH);
+  });
+
+  /**
+   * Surrogate-pair safety. `😀` (U+1F600) is one code point but two
+   * UTF-16 code units. Naive `slice(0, MAX_ADDENDUM_LENGTH)` on a
+   * string of emoji would land in the middle of the last codepoint's
+   * surrogate pair, leaving a lone high surrogate that downstream JSON
+   * encoders either reject or mangle. The sanitizer counts and slices
+   * by `Array.from` so this can never happen.
+   */
+  it('truncates emoji-heavy input at code-point boundaries', () => {
+    const input = '😀'.repeat(MAX_ADDENDUM_LENGTH + 100);
+    const result = sanitizeAddendum(input);
+    expect(Array.from(result)).toHaveLength(MAX_ADDENDUM_LENGTH);
+    // Every codepoint is the full emoji; never a lone surrogate. The
+    // matchAll iterator over the regex emits one match per scalar
+    // codepoint, so equality with the Array.from count confirms no
+    // half-pair remained.
+    expect([...result].every((c) => c === '😀')).toBe(true);
+  });
+
+  it('returns empty for empty string', () => {
+    expect(sanitizeAddendum('')).toBe('');
+  });
+});
+
+// ── combineInstructions ──────────────────────────────────────────────────────
+
+describe('combineInstructions', () => {
+  it('returns baseline unchanged when addendum is empty', () => {
+    expect(combineInstructions(BASELINE, '')).toBe(BASELINE);
+  });
+
+  it('returns baseline unchanged when addendum is whitespace only', () => {
+    expect(combineInstructions(BASELINE, '   \n\n  \t  ')).toBe(BASELINE);
+  });
+
+  it('joins baseline and addendum with a blank line', () => {
+    const result = combineInstructions('BASE', 'ADD');
+    expect(result).toBe('BASE\n\nADD');
+  });
+
+  it('trims the addendum before joining', () => {
+    const result = combineInstructions('BASE', '  ADD  ');
+    expect(result).toBe('BASE\n\nADD');
+  });
+
+  it('preserves multi-line addenda verbatim', () => {
+    const addendum = '- Rule one.\n- Rule two.';
+    const result = combineInstructions('BASE', addendum);
+    expect(result).toBe(`BASE\n\n${addendum}`);
+  });
+});
+
+// ── fetchAddendum (axios mocked) ─────────────────────────────────────────────
+
+describe('fetchAddendum', () => {
+  it('returns empty string when BLOCK_MCP_INSTRUCTIONS_OFF=1 (no HTTP call)', async () => {
+    process.env.BLOCK_MCP_INSTRUCTIONS_OFF = '1';
+    const result = await fetchAddendum('https://example.com');
+    expect(result).toBe('');
+    expect(vi.mocked(axios.get)).not.toHaveBeenCalled();
+  });
+
+  it('treats any value other than 1 in BLOCK_MCP_INSTRUCTIONS_OFF as off-not-set', async () => {
+    process.env.BLOCK_MCP_INSTRUCTIONS_OFF = '0';
+    vi.mocked(axios.get).mockResolvedValueOnce({ data: { addendum: 'hi' } });
+    const result = await fetchAddendum('https://example.com');
+    expect(result).toBe('hi');
+  });
+
+  it('issues GET to /wp-json/gk-block-api/v1/instructions', 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');
+  });
+
+  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');
+  });
+
+  it('passes a short timeout and JSON Accept header', async () => {
+    vi.mocked(axios.get).mockResolvedValueOnce({ data: { addendum: 'x' } });
+    await fetchAddendum('https://example.com');
+    const [, config] = vi.mocked(axios.get).mock.calls[0]!;
+    expect(config).toBeDefined();
+    expect(config!.timeout).toBeGreaterThan(0);
+    expect(config!.timeout).toBeLessThanOrEqual(10_000);
+    expect(config!.headers).toMatchObject({ Accept: 'application/json' });
+  });
+
+  /**
+   * Pins the hardening from BLOCK-19 review: a compromised or misconfigured
+   * WP site must not be able to redirect us to a different origin.
+   * `maxRedirects: 0` makes axios surface any 3xx as an error which falls
+   * through to baseline-only via the existing catch path.
+   */
+  it('disables redirect following (maxRedirects: 0)', async () => {
+    vi.mocked(axios.get).mockResolvedValueOnce({ data: { addendum: 'x' } });
+    await fetchAddendum('https://example.com');
+    const [, config] = vi.mocked(axios.get).mock.calls[0]!;
+    expect(config!.maxRedirects).toBe(0);
+  });
+
+  /**
+   * Pins the hardening from BLOCK-19 review: the HTTP layer must cap
+   * response body size before anything reaches `sanitizeAddendum`.
+   * Primary defense against unbounded payloads; sanitize is secondary.
+   */
+  it('caps response body size via maxContentLength', async () => {
+    vi.mocked(axios.get).mockResolvedValueOnce({ data: { addendum: 'x' } });
+    await fetchAddendum('https://example.com');
+    const [, config] = vi.mocked(axios.get).mock.calls[0]!;
+    expect(typeof config!.maxContentLength).toBe('number');
+    // Headroom over MAX_ADDENDUM_LENGTH but well under a megabyte —
+    // 16 KB is the chosen value; assert a window so an intentional
+    // bump up or down doesn't silently break the contract.
+    expect(config!.maxContentLength).toBeGreaterThan(MAX_ADDENDUM_LENGTH);
+    expect(config!.maxContentLength).toBeLessThanOrEqual(64 * 1024);
+  });
+
+  /**
+   * Same-host enforcement at the HTTP layer: a 3xx response from the
+   * site (whatever the Location header points to) is treated as an
+   * error and we fall back to baseline-only.
+   */
+  it('treats a 302 redirect as a fetch failure', async () => {
+    const err = Object.assign(new Error('Maximum number of redirects exceeded'), {
+      isAxiosError: true,
+      code: 'ERR_FR_MAX_REDIRECTS_EXCEEDED',
+    });
+    vi.mocked(axios.get).mockRejectedValueOnce(err);
+    vi.mocked(axios.isAxiosError).mockReturnValue(true);
+    const spy = vi.spyOn(console, 'error').mockImplementation(() => {});
+    expect(await fetchAddendum('https://example.com')).toBe('');
+    spy.mockRestore();
+  });
+
+  it('returns the sanitized addendum on success', async () => {
+    vi.mocked(axios.get).mockResolvedValueOnce({
+      data: { addendum: 'A\x00B' },
+    });
+    const result = await fetchAddendum('https://example.com');
+    expect(result).toBe('AB');
+  });
+
+  it('truncates an overly long remote response to MAX_ADDENDUM_LENGTH', async () => {
+    vi.mocked(axios.get).mockResolvedValueOnce({
+      data: { addendum: 'X'.repeat(MAX_ADDENDUM_LENGTH + 1000) },
+    });
+    const result = await fetchAddendum('https://example.com');
+    expect(result).toHaveLength(MAX_ADDENDUM_LENGTH);
+  });
+
+  it('strips Bidi overrides served by a compromised WP install', async () => {
+    vi.mocked(axios.get).mockResolvedValueOnce({
+      data: { addendum: 'evil‮block' },
+    });
+    const result = await fetchAddendum('https://example.com');
+    expect(result).not.toContain('‮');
+  });
+
+  it('returns empty when the response is missing the addendum field', async () => {
+    vi.mocked(axios.get).mockResolvedValueOnce({ data: { length: 0 } });
+    expect(await fetchAddendum('https://example.com')).toBe('');
+  });
+
+  it('returns empty when the response body is not an object', async () => {
+    vi.mocked(axios.get).mockResolvedValueOnce({ data: 'malformed' });
+    expect(await fetchAddendum('https://example.com')).toBe('');
+  });
+
+  it('returns empty when axios rejects (network error)', async () => {
+    vi.mocked(axios.get).mockRejectedValueOnce(new Error('ECONNREFUSED'));
+    // Suppress the stderr noise from the rejection log line.
+    const spy = vi.spyOn(console, 'error').mockImplementation(() => {});
+    expect(await fetchAddendum('https://example.com')).toBe('');
+    spy.mockRestore();
+  });
+
+  it('returns empty when the server replies non-2xx', async () => {
+    // axios with validateStatus throws on non-2xx by default; emulate that.
+    const err = Object.assign(new Error('Request failed with status code 500'), {
+      isAxiosError: true,
+      response: { status: 500, data: '' },
+    });
+    vi.mocked(axios.get).mockRejectedValueOnce(err);
+    vi.mocked(axios.isAxiosError).mockReturnValue(true);
+    const spy = vi.spyOn(console, 'error').mockImplementation(() => {});
+    expect(await fetchAddendum('https://example.com')).toBe('');
+    spy.mockRestore();
+  });
+
+  it('never throws — every failure path returns empty', async () => {
+    vi.mocked(axios.get).mockImplementation(() => {
+      throw new Error('synchronous boom');
+    });
+    const spy = vi.spyOn(console, 'error').mockImplementation(() => {});
+    await expect(fetchAddendum('https://example.com')).resolves.toBe('');
+    spy.mockRestore();
+  });
+});
+
+// ── getInstructions (the public entry point) ─────────────────────────────────
+
+describe('getInstructions', () => {
+  it('returns baseline alone when the site is unreachable', async () => {
+    vi.mocked(axios.get).mockRejectedValueOnce(new Error('ENOTFOUND'));
+    const spy = vi.spyOn(console, 'error').mockImplementation(() => {});
+    const result = await getInstructions('https://example.com');
+    expect(result).toBe(BASELINE);
+    spy.mockRestore();
+  });
+
+  it('returns baseline alone when BLOCK_MCP_INSTRUCTIONS_OFF=1', async () => {
+    process.env.BLOCK_MCP_INSTRUCTIONS_OFF = '1';
+    const result = await getInstructions('https://example.com');
+    expect(result).toBe(BASELINE);
+    expect(vi.mocked(axios.get)).not.toHaveBeenCalled();
+  });
+
+  it('returns baseline + addendum joined with a blank line', async () => {
+    vi.mocked(axios.get).mockResolvedValueOnce({
+      data: { addendum: 'CUSTOM RULE: prefer is-style-callout-info.' },
+    });
+    const result = await getInstructions('https://example.com');
+    expect(result.startsWith(BASELINE)).toBe(true);
+    expect(result.endsWith('CUSTOM RULE: prefer is-style-callout-info.')).toBe(true);
+    expect(result).toContain('\n\nCUSTOM RULE');
+  });
+
+  it('returns baseline alone when the site returns empty addendum', async () => {
+    vi.mocked(axios.get).mockResolvedValueOnce({ data: { addendum: '' } });
+    expect(await getInstructions('https://example.com')).toBe(BASELINE);
+  });
+});