mcp-wp-cli-terminus 0.1.0__py3-none-any.whl

mcp_wp_cli_terminus-0.1.0.dist-info/METADATA

@@ -0,0 +1,169 @@
+Metadata-Version: 2.4
+Name: mcp-wp-cli-terminus
+Version: 0.1.0
+Summary: MCP server for WP-CLI over local Docker, Pantheon Terminus, or SSH — run WP-CLI and byte-faithfully copy posts/meta between WordPress environments, with checksum verification.
+Project-URL: Homepage, https://github.com/EarthmanWeb/mcp-wp-cli-terminus
+Project-URL: Repository, https://github.com/EarthmanWeb/mcp-wp-cli-terminus
+Project-URL: Issues, https://github.com/EarthmanWeb/mcp-wp-cli-terminus/issues
+Author: EarthmanWeb
+License: MIT
+License-File: LICENSE
+Keywords: ai,anthropic,claude,claude-code,cli,devops,llm,mcp,migration,model-context-protocol,pantheon,terminus,wordpress,wp,wp-cli
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Internet :: WWW/HTTP :: Site Management
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Topic :: Utilities
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+# mcp-wp-cli-terminus
+
+**An [MCP](https://modelcontextprotocol.io) (Model Context Protocol) server that lets Claude and other AI agents run [WP-CLI](https://wp-cli.org) against WordPress — over local Docker, [Pantheon Terminus](https://docs.pantheon.io/terminus), or SSH — and byte-faithfully copy posts and post meta between environments with checksum verification.**
+
+Built for developers using **Claude Code / Claude Desktop** (or any MCP client) to operate **WordPress** sites — including **Pantheon** multidevs reached through **Terminus** — without hand-assembling fragile `wp eval` commands.
+
+<sub>`wp-cli` · `wordpress` · `terminus` · `pantheon` · `mcp` · `model-context-protocol` · `claude` · `claude-code` · `anthropic` · `wordpress-migration` · `devops`</sub>
+
+---
+
+## Why
+
+Moving a WordPress post's body or custom fields between environments (e.g. pushing a block-based front page from local to a Pantheon multidev) is deceptively hard to do correctly:
+
+- `wp post update --post_content` **truncates at newlines** ([wp-cli#2712](https://github.com/wp-cli/wp-cli/issues/2712)).
+- Piping content over STDIN **hangs on `terminus remote:wp`** ([terminus#1615](https://github.com/pantheon-systems/terminus/issues/1615)).
+- Hand-pasting base64 into an agent prompt is **lossy** — a single flipped byte silently corrupts production.
+- Large payloads passed as one shell argument hit the Linux **`MAX_ARG_STRLEN` (131072 bytes)** limit and fail with `E2BIG`.
+- Post **meta** with serialized arrays / multiple values per key is easy to corrupt by re-serializing.
+
+This server solves all of that: content is read, base64-encoded **in code**, delivered over a transport-safe path, and then **re-read and checksum-compared** to the source. A mismatch is reported, never silently trusted.
+
+## Tools
+
+| Tool | What it does |
+|------|--------------|
+| `wp_cli` | Run any WP-CLI command against a configured site — `target: local` (Docker) or `target: production` (Terminus or SSH, chosen by config). Destructive commands are guarded on production. |
+| `wp_copy_post` | Byte-faithfully copy a post's `post_content` from one environment to another, with an **md5 round-trip verification**. |
+| `wp_copy_post_meta` | Byte-faithfully copy a post's **complete** meta (all custom fields — serialized arrays, multiple values per key, ACF repeaters) between environments, with a canonical **checksum verification**. Copy all keys (full mirror) or an allow-list. |
+
+### Correctness guarantees
+
+- **Never routes content through the model's text.** Payloads are read into the server and base64-encoded in code.
+- **Checksum-verified.** Every copy re-reads the destination and compares it to the transferred source; `verified: false` + an error on any mismatch.
+- **Transport-agnostic.** The same logic runs over local Docker, Pantheon Terminus, and WP-CLI `--ssh`.
+- **Large payloads.** Docker/SSH deliver PHP over STDIN (`wp eval-file -`, exempt from the argv size limit); Terminus uses a size-guarded argv path and fails loud rather than emitting a raw `E2BIG`.
+- **Meta fidelity.** Values are round-tripped so WordPress's own `maybe_serialize()` reproduces the exact stored `meta_value` — arrays stay arrays, and strings that merely look serialized stay strings.
+- **Production guard.** Writes to a production destination require `confirm: true` when `PROD_GUARD` is enabled.
+
+## Install & run
+
+The server is **pure Python (stdlib only, zero dependencies)**.
+
+### With `uvx` (recommended — no install)
+
+```jsonc
+// Claude Desktop / Claude Code MCP config
+{
+  "mcpServers": {
+    "wp-cli": {
+      "command": "uvx",
+      "args": ["mcp-wp-cli-terminus"]
+    }
+  }
+}
+```
+
+### With `pip`
+
+```bash
+pip install mcp-wp-cli-terminus
+```
+
+```jsonc
+{
+  "mcpServers": {
+    "wp-cli": { "command": "mcp-wp-cli-terminus" }
+  }
+}
+```
+
+### From source
+
+```bash
+git clone https://github.com/EarthmanWeb/mcp-wp-cli-terminus
+cd mcp-wp-cli-terminus
+python -m wp_cli_mcp   # PYTHONPATH=src, or `pip install -e .`
+```
+
+## Configure
+
+The server reads `<project-root>/.serena/wp-cli.conf` at runtime (set `CLAUDE_PROJECT_DIR` to point at your project). Copy [`wp-cli.conf.example`](wp-cli.conf.example) and edit:
+
+```ini
+DEFAULT_SITE=example-site
+PROD_GUARD=true
+
+[site:example-site]
+LOCAL_CONTAINER=my-container       # docker container running WP-CLI
+LOCAL_PATH=/var/www/html           # WordPress path inside the container
+TERMINUS_SITE=example              # Pantheon site — production routes over Terminus
+TERMINUS_ENV=dev                   # default env (override per call)
+# — or, for a non-Pantheon remote, omit TERMINUS_* and set:
+# REMOTE_SSH=deploy@example.com:22/var/www/html
+```
+
+- **Production transport is chosen by config:** `TERMINUS_SITE` → `terminus remote:wp`; otherwise `REMOTE_SSH` → WP-CLI `--ssh`.
+- **Multi-site:** add more `[site:NAME]` sections and pass `site` per call.
+
+**Never commit `.serena/wp-cli.conf`** — it may contain hostnames/SSH strings. The shipped [`.gitignore`](.gitignore) excludes it.
+
+## Usage examples
+
+```jsonc
+// Run a WP-CLI command locally
+{ "tool": "wp_cli", "args": "plugin list --status=active --format=json" }
+
+// Run against production (Terminus or SSH per config)
+{ "tool": "wp_cli", "args": "option get siteurl", "target": "production" }
+
+// Copy a front page's block markup from local to production, verified
+{ "tool": "wp_copy_post", "post_id": 42, "from": "local", "to": "production", "confirm": true }
+
+// Copy ALL meta for a post (full mirror), verified
+{ "tool": "wp_copy_post_meta", "post_id": 42, "from": "local", "to": "production", "confirm": true }
+
+// Copy only specific meta keys
+{ "tool": "wp_copy_post_meta", "post_id": 42, "from": "local", "to": "production",
+  "keys": ["_thumbnail_id", "my_field"], "confirm": true }
+```
+
+Each copy returns `verified: true/false` with `src_md5` / `dst_md5`, the delivery mode, and per-side transport.
+
+## Debug logging
+
+Failures (non-zero WP-CLI exits) are appended to a log in your system temp dir — **failures only**, successes are never logged:
+
+- Location: `${TMPDIR}/wp-cli-mcp/failures.log` (override with `WP_CLI_MCP_LOG_DIR`).
+- Disable entirely with `WP_CLI_MCP_LOG=0`.
+- SSH connection strings are redacted in the log.
+
+## Requirements
+
+- Python 3.8+
+- [WP-CLI](https://wp-cli.org) reachable via one of: a local Docker container (`docker exec`), Pantheon [Terminus](https://docs.pantheon.io/terminus) on the host, or a host WP-CLI with `--ssh`.
+
+## Tests
+
+```bash
+python -m unittest discover -s tests -v
+```
+
+54 stdlib-only unit tests cover config parsing, transport selection (local/Terminus/SSH), the argv size guard, newline handling, PHP-key safety, and the full copy/verify orchestration via an injectable command-runner seam (no real WP-CLI invoked).
+
+## License
+
+[MIT](LICENSE)

mcp_wp_cli_terminus-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+wp_cli_mcp/__init__.py,sha256=F1rzIFikYTp2NscHkbY06k7uOsoETjQX2YKW7-E9Hqg,1562
+wp_cli_mcp/__main__.py,sha256=IJtKrKqAneO0nmmy1ilRxBEVBawVB7myVRVtR_DJvZg,172
+wp_cli_mcp/command.py,sha256=AEub3m01wOFzbZt-LS3guBPmlsHz05siDMAd-jgF0tI,12441
+wp_cli_mcp/config.py,sha256=7CSsab3gW2QmV7TzamyR2eGsPx_h6EyvWdPCRZhq4Zo,6513
+wp_cli_mcp/tools.py,sha256=aV9LXXEi-iHJFIefDTmuZ2HdlSkDV6X-vTqWSt6AnhE,29207
+wp_cli_mcp/transport.py,sha256=5pLEVFftnzG2pTFPwWbOB5t5EYBnsO8EEQzfxRfypM0,4810
+mcp_wp_cli_terminus-0.1.0.dist-info/METADATA,sha256=CkM1OeiU3UsAtGje67YlzS2yEa26RClmmiwT4sql-8o,7911
+mcp_wp_cli_terminus-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+mcp_wp_cli_terminus-0.1.0.dist-info/entry_points.txt,sha256=ye8OcxrHlxc-ESadDV6NqW4kVmcgns9Tv4NzfT-IrnM,56
+mcp_wp_cli_terminus-0.1.0.dist-info/licenses/LICENSE,sha256=8zLVabyV4oHMDiRDUDnLfwhQ55ynSBNK3-67CEFNrhU,1068
+mcp_wp_cli_terminus-0.1.0.dist-info/RECORD,,

mcp_wp_cli_terminus-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

mcp_wp_cli_terminus-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+mcp-wp-cli-terminus = wp_cli_mcp:main

mcp_wp_cli_terminus-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 EarthmanWeb
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

wp_cli_mcp/__init__.py

@@ -0,0 +1,59 @@
+#!/usr/bin/env python3
+"""wp_cli — a transport-agnostic WP-CLI MCP server package.
+
+Exposes a stdio JSON-RPC MCP server with three tools:
+  wp_cli, wp_copy_post, wp_copy_post_meta.
+
+Public API is re-exported here so callers (and tests) can `from wp_cli import ...`
+without reaching into submodules.
+"""
+
+from .config import (
+    CONF_RELATIVE_PATH,
+    DESTRUCTIVE_PREFIXES,
+    SEARCH_REPLACE,
+    ConfigError,
+    get_project_root,
+    guard_enabled,
+    load_config,
+    require,
+    resolve_site,
+)
+from .command import (
+    MAX_ARG_STRLEN,
+    build_command,
+    is_destructive,
+    log_failure,
+    run_php_eval,
+    run_wp,
+    set_runner,
+    transport_label,
+    uses_terminus,
+)
+from .tools import (
+    TOOL_DEFINITIONS,
+    TOOL_REGISTRY,
+    tool_wp_cli,
+    tool_wp_copy_post,
+    tool_wp_copy_post_meta,
+)
+from .transport import (
+    SERVER_NAME,
+    SERVER_VERSION,
+    PROTOCOL_VERSION,
+    handle_initialize,
+    handle_tools_call,
+    handle_tools_list,
+    main,
+)
+
+__all__ = [
+    "CONF_RELATIVE_PATH", "DESTRUCTIVE_PREFIXES", "SEARCH_REPLACE", "ConfigError",
+    "get_project_root", "guard_enabled", "load_config", "require", "resolve_site",
+    "MAX_ARG_STRLEN", "build_command", "is_destructive", "log_failure",
+    "run_php_eval", "run_wp", "set_runner", "transport_label", "uses_terminus",
+    "TOOL_DEFINITIONS", "TOOL_REGISTRY",
+    "tool_wp_cli", "tool_wp_copy_post", "tool_wp_copy_post_meta",
+    "SERVER_NAME", "SERVER_VERSION", "PROTOCOL_VERSION",
+    "handle_initialize", "handle_tools_call", "handle_tools_list", "main",
+]

wp_cli_mcp/__main__.py

@@ -0,0 +1,7 @@
+#!/usr/bin/env python3
+"""Entry point for `python -m wp_cli` (and the console-script when packaged)."""
+
+from .transport import main
+
+if __name__ == "__main__":
+    main()

wp_cli_mcp/command.py

@@ -0,0 +1,278 @@
+#!/usr/bin/env python3
+"""WP-CLI MCP server — command construction, transport selection, execution seam.
+
+Builds the full argv for each transport (local Docker / Pantheon Terminus / SSH),
+detects destructive commands, and runs commands through an injectable runner seam
+(set_runner) so orchestration can be unit-tested without a real WP-CLI. Stdlib only.
+"""
+
+import os
+import subprocess
+import tempfile
+import time
+from typing import Dict, List, Optional
+
+from .config import (
+    CONF_RELATIVE_PATH,
+    DESTRUCTIVE_PREFIXES,
+    SEARCH_REPLACE,
+    ConfigError,
+    require,
+)
+
+# ──────────────────────────────────────────────────────────────────
+# Failure logging (temp dir, failures only)
+# ──────────────────────────────────────────────────────────────────
+#
+# Debugging aid: when a WP-CLI invocation exits non-zero we append a record to a
+# log FILE IN THE SYSTEM TEMP DIR (never inside the package/code tree). Successful
+# calls are NOT logged — this keeps the log to actionable failures only. Override
+# the location with WP_CLI_MCP_LOG_DIR; disable entirely with WP_CLI_MCP_LOG=0.
+
+def _log_dir() -> str:
+    return os.environ.get("WP_CLI_MCP_LOG_DIR") or os.path.join(tempfile.gettempdir(), "wp-cli-mcp")
+
+
+def _logging_enabled() -> bool:
+    return os.environ.get("WP_CLI_MCP_LOG", "1") not in ("0", "false", "no", "off")
+
+
+def log_failure(argv, returncode, stderr, note: str = ""):
+    """Append a failure record to the temp-dir log. Best-effort: never raises."""
+    if not _logging_enabled():
+        return
+    try:
+        d = _log_dir()
+        os.makedirs(d, exist_ok=True)
+        if isinstance(stderr, (bytes, bytearray)):
+            stderr = stderr.decode("utf-8", "replace")
+        # Redact anything after --ssh= (may contain a host/user) for safety.
+        safe_argv = []
+        for a in argv:
+            safe_argv.append(a.split("=", 1)[0] + "=<redacted>" if a.startswith("--ssh=") else a)
+        stamp = time.strftime("%Y-%m-%dT%H:%M:%S")
+        line = (
+            f"[{stamp}] rc={returncode}"
+            + (f" note={note}" if note else "")
+            + f"\n  cmd: {' '.join(safe_argv)}"
+            + f"\n  stderr: {(stderr or '').strip()[:2000]}\n"
+        )
+        with open(os.path.join(d, "failures.log"), "a", encoding="utf-8") as fh:
+            fh.write(line)
+    except Exception:
+        pass  # logging must never break the tool
+
+# Linux caps a SINGLE argv/env string at MAX_ARG_STRLEN = 32 * PAGE_SIZE (4096)
+# = 131072 bytes, independent of total ARG_MAX. A `wp eval <php>` invocation
+# passes the whole PHP as one argv element, so large payloads must go via STDIN
+# (`wp eval-file -`) which is exempt. This is the ceiling we pre-check against.
+MAX_ARG_STRLEN = 131072
+
+
+# ──────────────────────────────────────────────────────────────────
+# Destructive detection
+# ──────────────────────────────────────────────────────────────────
+
+def _leading_words(arg_tokens: List[str]) -> List[str]:
+    """Return the leading non-flag tokens (the WP-CLI command path)."""
+    words = []
+    for tok in arg_tokens:
+        if tok.startswith("-"):
+            break
+        words.append(tok)
+    return words
+
+
+def is_destructive(arg_tokens: List[str]) -> bool:
+    """True if the command matches a destructive prefix.
+
+    search-replace is destructive UNLESS --dry-run is present.
+    """
+    words = _leading_words(arg_tokens)
+
+    if words[:1] == SEARCH_REPLACE:
+        return "--dry-run" not in arg_tokens
+
+    for prefix in DESTRUCTIVE_PREFIXES:
+        if words[: len(prefix)] == prefix:
+            return True
+    return False
+
+
+def uses_terminus(block: Dict[str, str]) -> bool:
+    """Production transport for this site is Terminus iff TERMINUS_SITE is set."""
+    return bool(block.get("TERMINUS_SITE", "").strip())
+
+
+# ──────────────────────────────────────────────────────────────────
+# Command construction
+# ──────────────────────────────────────────────────────────────────
+
+def build_command(
+    block: Dict[str, str],
+    site_name: str,
+    target: str,
+    arg_tokens: List[str],
+    env: Optional[str] = None,
+    *,
+    stdin: bool = False,
+) -> List[str]:
+    """Build the full argv for the requested target.
+
+    local:               docker exec [-i] [-w WORKDIR] CONTAINER wp --path=PATH <args> --allow-root
+    production (ssh):     docker exec [-i] CONTAINER wp --ssh=REMOTE_SSH <args> --allow-root
+    production (terminus): terminus remote:wp TERMINUS_SITE.<env> -- <args>
+
+    Terminus runs on the HOST (not via docker exec) and takes no --path/--allow-root.
+    The production transport is chosen by the site's conf: TERMINUS_SITE → Terminus,
+    else REMOTE_SSH → WP-CLI --ssh.
+
+    `stdin=True` adds `docker exec -i` for the Docker transports so a piped payload
+    actually reaches the process (without -i, docker exec delivers an empty STDIN).
+    Terminus does not use STDIN (it hangs — Pantheon #1615), so the flag is ignored
+    there.
+    """
+    if target == "production" and uses_terminus(block):
+        terminus_site = require(block, "TERMINUS_SITE", site_name)
+        resolved_env = (env or block.get("TERMINUS_ENV", "")).strip()
+        if not resolved_env:
+            raise ConfigError(
+                f"No Terminus environment for [site:{site_name}]. Set TERMINUS_ENV in "
+                f"{CONF_RELATIVE_PATH} or pass env=<dev|test|live|...>."
+            )
+        cmd: List[str] = ["terminus", "remote:wp", f"{terminus_site}.{resolved_env}", "--"]
+        cmd += arg_tokens
+        return cmd
+
+    container = require(block, "LOCAL_CONTAINER", site_name)
+    cmd = ["docker", "exec"]
+    if stdin:
+        cmd.append("-i")
+
+    if target == "production":
+        remote_ssh = require(block, "REMOTE_SSH", site_name)
+        cmd += [container, "wp", f"--ssh={remote_ssh}"]
+        cmd += arg_tokens
+        cmd += ["--allow-root"]
+    else:
+        path = require(block, "LOCAL_PATH", site_name)
+        workdir = block.get("LOCAL_WORKDIR", "")
+        if workdir:
+            cmd += ["-w", workdir]
+        cmd += [container, "wp", f"--path={path}"]
+        cmd += arg_tokens
+        cmd += ["--allow-root"]
+
+    return cmd
+
+
+def transport_label(block: Dict[str, str], target: str) -> str:
+    """Human-readable transport for a side: local / terminus / ssh."""
+    if target != "production":
+        return "local"
+    return "terminus" if uses_terminus(block) else "ssh"
+
+
+# ──────────────────────────────────────────────────────────────────
+# Execution seam
+# ──────────────────────────────────────────────────────────────────
+
+# Command runner seam: production uses subprocess.run; tests inject a fake via
+# set_runner() to exercise orchestration without a real WP-CLI. The runner
+# receives (argv, text, stdin) and returns an object with
+# .returncode/.stdout/.stderr (a subprocess.CompletedProcess in production).
+# `stdin` (bytes or None) is fed to the process's standard input — used for the
+# large-payload `wp eval-file -` path that sidesteps the argv size limit.
+def _default_runner(argv: List[str], text: bool, stdin=None):
+    return subprocess.run(argv, capture_output=True, text=text, input=stdin)
+
+
+_RUNNER = _default_runner
+
+
+def set_runner(fn):
+    """Override the command runner (tests only). Pass None to restore the default.
+
+    The runner is called as fn(argv, text, stdin=None). Fakes may accept just
+    (argv, text) if they never exercise the STDIN path, but supporting the third
+    parameter is recommended.
+    """
+    global _RUNNER
+    _RUNNER = fn or _default_runner
+
+
+def _call_runner(argv, text, stdin=None):
+    """Invoke the runner, tolerating fakes that only accept (argv, text).
+
+    Logs (to the temp-dir failure log) any invocation that exits non-zero, so
+    failures leave a durable, greppable trace. Successes are not logged.
+    """
+    try:
+        proc = _RUNNER(argv, text, stdin)
+    except TypeError:
+        if stdin is not None:
+            raise
+        proc = _RUNNER(argv, text)
+    rc = getattr(proc, "returncode", None)
+    if rc not in (0, None):
+        log_failure(argv, rc, getattr(proc, "stderr", ""))
+    return proc
+
+
+def run_wp(block: Dict[str, str], site_name: str, target: str, arg_tokens: List[str], env: Optional[str], *, text: bool = True):
+    """Run a single WP-CLI invocation on the given side and return (proc, full_cmd).
+
+    `text=False` captures raw bytes (used when reading post_content so no locale
+    re-encoding can alter it). The command is built via build_command(), so
+    transport selection (Docker/Terminus/SSH) is identical everywhere. Execution
+    is delegated to the injectable runner seam.
+    """
+    full_cmd = build_command(block, site_name, target, arg_tokens, env)
+    return _call_runner(full_cmd, text), full_cmd
+
+
+def run_php_eval(block, site_name, target, php, env, *, text=True):
+    """Execute a PHP snippet via WP-CLI, choosing a transport-safe delivery.
+
+    A `wp eval <php>` call passes the whole PHP as ONE argv element, which Linux
+    caps at MAX_ARG_STRLEN (131072 bytes) — large post_content/meta payloads blow
+    past it with E2BIG. To stay correct on every transport:
+
+    - local / ssh (docker exec): deliver the PHP on STDIN via `wp eval-file -`,
+      which is exempt from the argv size limit and works for any payload size.
+      NOTE: `wp eval-file` executes a PHP *file*, so the payload MUST start with a
+      `<?php` open tag or WP-CLI just echoes it verbatim (proven on WP-CLI 2.12).
+      `wp eval` (the argv form) is the opposite — it wants a raw expression with
+      NO open tag. We add the tag only on the STDIN path.
+    - terminus: STDIN piping hangs over `terminus remote:wp` (Pantheon issue
+      #1615), so we must use the argv `wp eval` form (no open tag). If the single
+      token would exceed MAX_ARG_STRLEN we FAIL LOUD with a clear error rather than
+      emit a raw E2BIG.
+
+    `php` is a raw expression body (no `<?php`); this function adds the tag where
+    the chosen delivery needs it. Returns (proc, full_cmd, mode); mode is
+    "stdin" or "argv".
+    """
+    php_str = php.decode("utf-8") if isinstance(php, (bytes, bytearray)) else php
+
+    if target == "production" and uses_terminus(block):
+        # Terminus: argv `wp eval` (raw expression, no open tag). Guard the size.
+        token_len = len(php_str.encode("utf-8"))
+        if token_len >= MAX_ARG_STRLEN:
+            raise ConfigError(
+                f"PHP eval payload is {token_len} bytes, over the {MAX_ARG_STRLEN}-byte "
+                f"single-argument execve limit, and the Terminus transport cannot use STDIN "
+                f"(hangs — Pantheon issue #1615). This post/meta is too large to copy to a "
+                f"Terminus destination in one call. Copy to a local/SSH destination, or split "
+                f"the payload."
+            )
+        full_cmd = build_command(block, site_name, target, ["eval", php_str], env)
+        return _call_runner(full_cmd, text), full_cmd, "argv"
+
+    # local / ssh: STDIN via `wp eval-file -` (no argv size limit). eval-file runs
+    # a PHP FILE, so prepend the `<?php` open tag; requires `docker exec -i`
+    # (stdin=True) or the payload arrives empty.
+    file_php = "<?php " + php_str
+    full_cmd = build_command(block, site_name, target, ["eval-file", "-"], env, stdin=True)
+    payload = file_php if text else file_php.encode("utf-8")
+    return _call_runner(full_cmd, text, payload), full_cmd, "stdin"