chore: record the vendored adapter's one deviation as a script (#101)

CLAUDE.md says twice, in bold, that includes/lib/wp-mcp/ is vendored and never
hand-edited. It has been hand-edited: 147 i18n text domains across 18 files
were rewritten from `mcp-adapter` to `saddle`.

The rewrite itself is defensible — the self-hosted build is the only one that
ships the library (the .org zip excludes the whole directory), and showing
translators two text domains for one plugin is worse than the deviation. What
was not defensible is that it existed only as edits in the tree. Drop in a
fresh upstream release and it is gone, silently, because nothing fails.

So it is now written down and re-runnable. Re-vendoring is: replace the
directory, run scripts/revendor-wp-mcp.php, run the suite. `--check` makes no
changes and exits non-zero when work is pending, which is the pre-release
guard against exactly the silent-revert case.

Verified by reproduction rather than assertion: reverting the whole library to
a pristine text domain and re-running the script restores all 147 occurrences
and leaves includes/lib/wp-mcp byte-identical to what main carries.

The script rewrites ONLY the text-domain argument, recognised by the closing
parenthesis that follows it. `'mcp-adapter'` also appears five times as an
ability category and as the adapter's own server id; those are identifiers
that upstream code looks up by name, and renaming them would break lookups.
That distinction is why a blanket find-and-replace would have been wrong, and
it is the reason this needed to be a script rather than a sed one-liner in a
comment.

scripts/ is excluded from both build channels — the src list is `['**', …]`
with exclusions, so a new top-level directory ships by default unless it is
named. Verified against the built zip.


Claude-Session: https://claude.ai/code/session_01GkZr73cqaSesHRDG89Yy8S

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: ifahimreza

CLAUDE.md

@@ -352,6 +352,15 @@ change. `Tested up to:` moves only when Fahim has verified against a newer WP.
 - Don't wire up `Saddle_Ecosystem`.
 - Don't put licensing, upsell or builder-specific code in free.
 - Don't edit `includes/lib/wp-mcp/` — it is vendored. Fix upstream and re-vendor.
+  **One deviation exists and is recorded, not hand-applied:** every i18n text
+  domain in there is rewritten to `saddle`, so the self-hosted build (the only
+  one that ships the library) shows translators one domain instead of two.
+  That rewrite lives in `scripts/revendor-wp-mcp.php`. Re-vendoring is: drop in
+  upstream, run the script, run the suite. `--check` reports pending work and
+  exits non-zero — run it before a release, because a fresh upstream copy
+  silently reverts the rewrite and nothing else would notice. The script
+  touches only the text-domain *argument*; `'mcp-adapter'` also appears as an
+  ability category and the adapter's server id, and those are identifiers.
 
 ---
 

Gruntfile.js

@@ -81,6 +81,9 @@ module.exports = function ( grunt ) {
 							// config, not plugin code. Excluded explicitly rather
 							// than relying on how the globber treats dot-dirs.
 							'!.agents/**',
+							// Developer CLI tooling — re-vendoring helpers and
+							// the like. Never plugin code.
+							'!scripts/**',
 							'!Gruntfile.js',
 							'!package.json',
 							'!package-lock.json',

scripts/revendor-wp-mcp.php

@@ -0,0 +1,114 @@
+#!/usr/bin/env php
+<?php
+/**
+ * Re-apply Saddle's one recorded change to the vendored MCP adapter.
+ *
+ * `includes/lib/wp-mcp/` is vendored and must not be hand-edited — CLAUDE.md
+ * says so twice. Exactly one deviation is nevertheless carried, deliberately:
+ * every i18n text domain inside it is rewritten from `mcp-adapter` to `saddle`,
+ * so the self-hosted build (the only build that ships the library at all — the
+ * WordPress.org zip excludes it) exposes one text domain to translators rather
+ * than two.
+ *
+ * That deviation was applied by hand, and a hand-applied change to a vendored
+ * tree is lost the moment someone drops in a fresh upstream copy — silently,
+ * because nothing fails. This script is the change, written down and
+ * re-runnable, so re-vendoring is:
+ *
+ *     1. replace includes/lib/wp-mcp/ with the upstream release
+ *     2. php scripts/revendor-wp-mcp.php
+ *     3. composer test && composer lint
+ *
+ * It is idempotent: running it on an already-patched tree reports zero
+ * changes. `--check` makes no changes and exits non-zero if any are pending,
+ * which is what to run before a release.
+ *
+ * WHAT IT DELIBERATELY DOES NOT TOUCH: `'mcp-adapter'` also appears as an
+ * ability category and as the adapter's own server id. Those are identifiers,
+ * not translatable strings, and rewriting them would rename things upstream
+ * code looks up by name. Only the text-domain ARGUMENT is rewritten — the
+ * last argument of an i18n call, recognised by the closing parenthesis that
+ * follows it.
+ *
+ * Not shipped: `scripts/` is excluded from both build channels.
+ *
+ * @package Saddle
+ */
+
+// This is a developer CLI tool, not plugin code — it runs outside WordPress.
+if ( 'cli' !== PHP_SAPI ) {
+	fwrite( STDERR, "This script is CLI-only.\n" );
+	exit( 1 );
+}
+
+$saddle_lib = dirname( __DIR__ ) . '/includes/lib/wp-mcp';
+
+if ( ! is_dir( $saddle_lib ) ) {
+	// The WordPress.org build has no vendored library, and neither does a
+	// checkout that never had one. Nothing to do is a success, not a failure.
+	fwrite( STDOUT, "No vendored adapter at includes/lib/wp-mcp — nothing to patch.\n" );
+	exit( 0 );
+}
+
+$saddle_check_only = in_array( '--check', $argv, true );
+
+/**
+ * Only ever the text-domain argument: a quoted 'mcp-adapter' whose next
+ * non-whitespace character closes the call. An ability category or a server
+ * id is followed by a comma, so neither matches.
+ */
+$saddle_pattern = "/'mcp-adapter'(\s*\))/";
+
+$saddle_files   = new RecursiveIteratorIterator( new RecursiveDirectoryIterator( $saddle_lib ) );
+$saddle_touched = array();
+$saddle_total   = 0;
+
+foreach ( $saddle_files as $saddle_file ) {
+	if ( ! $saddle_file->isFile() || 'php' !== strtolower( $saddle_file->getExtension() ) ) {
+		continue;
+	}
+
+	$saddle_path     = $saddle_file->getPathname();
+	$saddle_contents = file_get_contents( $saddle_path );
+	if ( false === $saddle_contents ) {
+		fwrite( STDERR, sprintf( "Could not read %s\n", $saddle_path ) );
+		exit( 1 );
+	}
+
+	$saddle_count   = 0;
+	$saddle_patched = preg_replace( $saddle_pattern, "'saddle'\$1", $saddle_contents, -1, $saddle_count );
+
+	if ( ! $saddle_count ) {
+		continue;
+	}
+
+	$saddle_total    += $saddle_count;
+	$saddle_touched[] = sprintf( '%s (%d)', substr( $saddle_path, strlen( $saddle_lib ) + 1 ), $saddle_count );
+
+	if ( ! $saddle_check_only && false === file_put_contents( $saddle_path, $saddle_patched ) ) {
+		fwrite( STDERR, sprintf( "Could not write %s\n", $saddle_path ) );
+		exit( 1 );
+	}
+}
+
+sort( $saddle_touched );
+
+if ( ! $saddle_total ) {
+	fwrite( STDOUT, "Vendored adapter already carries Saddle's text domain — nothing to do.\n" );
+	exit( 0 );
+}
+
+fwrite(
+	STDOUT,
+	sprintf(
+		"%s %d text-domain occurrence(s) across %d file(s):\n  %s\n",
+		$saddle_check_only ? 'PENDING:' : 'Rewrote',
+		$saddle_total,
+		count( $saddle_touched ),
+		implode( "\n  ", $saddle_touched )
+	)
+);
+
+// --check is for CI and pre-release: pending work is a failure there, because
+// it means the tree was re-vendored and this was never re-run.
+exit( $saddle_check_only ? 1 : 0 );