mcp-wp-cli-terminus 0.2.0__tar.gz → 0.3.0__tar.gz

{mcp_wp_cli_terminus-0.2.0 → mcp_wp_cli_terminus-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mcp-wp-cli-terminus
-Version: 0.2.0
+Version: 0.3.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
@@ -46,14 +46,21 @@ This server solves all of that: content is read, base64-encoded **in code**, del
 
 | Tool | What it does |
 |------|--------------|
+| `wp_init_config` | Guided setup: detects your Docker container, WordPress path, and Terminus site, then writes `.serena/wp-cli.conf` (asking you for anything it can't detect). |
 | `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. |
+| `wp_sync_post` | **Sync** a post's `post_content` onto the **same post ID** in another environment (updates an existing post; e.g. a multidev cloned from the same DB), with an **md5 round-trip verification**. |
+| `wp_sync_post_meta` | **Sync** a post's **complete** meta (serialized arrays, multiple values per key, ACF repeaters) onto the **same post ID** in another environment, with a canonical **checksum verification**. All keys (full mirror) or an allow-list. |
+| `wp_clone_post` | **Clone** a post to another environment as a **NEW** post — the destination assigns its own ID (returned as `new_id`). Use when the post doesn't exist on the destination yet. Copies fields + all meta, verifies, and reports meta keys that hold ID references for manual remapping. |
+
+### Sync vs. clone
+
+- **Sync** (`wp_sync_post`, `wp_sync_post_meta`) updates an **existing** post that shares the **same ID** on both sides — the right tool when the environments were cloned from the same database (a Pantheon multidev, a staging copy). It fails if the destination ID doesn't exist.
+- **Clone** (`wp_clone_post`) **creates a new** post on the destination from a source post; the destination assigns a fresh ID. Use it when the content is new to the destination (e.g. pushing a locally-authored post/alert up to a multidev). Meta values that look like ID references (`_thumbnail_id`, ACF relationship/image fields) are copied verbatim and **reported** — never silently remapped across databases.
 
 ### 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.
+- **Checksum-verified.** Every sync/clone 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.
@@ -141,18 +148,25 @@ TERMINUS_ENV=dev                   # default env (override per call)
 // 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 }
+// SYNC a front page's block markup onto the SAME post ID on production, verified
+{ "tool": "wp_sync_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 }
+// SYNC ALL meta for a post (full mirror) onto the same ID, verified
+{ "tool": "wp_sync_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",
+// SYNC only specific meta keys
+{ "tool": "wp_sync_post_meta", "post_id": 42, "from": "local", "to": "production",
   "keys": ["_thumbnail_id", "my_field"], "confirm": true }
+
+// CLONE a locally-authored post to production as a NEW post (returns new_id)
+{ "tool": "wp_clone_post", "post_id": 268529, "from": "local", "to": "production", "confirm": true }
+
+// Clone but force the new post to draft
+{ "tool": "wp_clone_post", "post_id": 268529, "from": "local", "to": "production",
+  "overrides": { "post_status": "draft" }, "confirm": true }
 ```
 
-Each copy returns `verified: true/false` with `src_md5` / `dst_md5`, the delivery mode, and per-side transport.
+`wp_sync_*` return `verified: true/false` with `src_md5` / `dst_md5`, the delivery mode, and per-side transport. `wp_clone_post` returns `new_id`, `verified`, `content_verified`, `meta_verified`, and `id_reference_keys` (meta keys to review).
 
 ## Debug logging
 
@@ -173,7 +187,7 @@ Failures (non-zero WP-CLI exits) are appended to a log in your system temp dir
 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).
+70 stdlib-only unit tests (split by area under `tests/`) cover config parsing, transport selection (local/Terminus/SSH), the argv size guard, newline handling, PHP-key safety, id-reference detection, and the full sync/clone/verify orchestration via an injectable command-runner seam (no real WP-CLI invoked).
 
 ## Releasing
 

{mcp_wp_cli_terminus-0.2.0 → mcp_wp_cli_terminus-0.3.0}/README.md

@@ -24,14 +24,21 @@ This server solves all of that: content is read, base64-encoded **in code**, del
 
 | Tool | What it does |
 |------|--------------|
+| `wp_init_config` | Guided setup: detects your Docker container, WordPress path, and Terminus site, then writes `.serena/wp-cli.conf` (asking you for anything it can't detect). |
 | `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. |
+| `wp_sync_post` | **Sync** a post's `post_content` onto the **same post ID** in another environment (updates an existing post; e.g. a multidev cloned from the same DB), with an **md5 round-trip verification**. |
+| `wp_sync_post_meta` | **Sync** a post's **complete** meta (serialized arrays, multiple values per key, ACF repeaters) onto the **same post ID** in another environment, with a canonical **checksum verification**. All keys (full mirror) or an allow-list. |
+| `wp_clone_post` | **Clone** a post to another environment as a **NEW** post — the destination assigns its own ID (returned as `new_id`). Use when the post doesn't exist on the destination yet. Copies fields + all meta, verifies, and reports meta keys that hold ID references for manual remapping. |
+
+### Sync vs. clone
+
+- **Sync** (`wp_sync_post`, `wp_sync_post_meta`) updates an **existing** post that shares the **same ID** on both sides — the right tool when the environments were cloned from the same database (a Pantheon multidev, a staging copy). It fails if the destination ID doesn't exist.
+- **Clone** (`wp_clone_post`) **creates a new** post on the destination from a source post; the destination assigns a fresh ID. Use it when the content is new to the destination (e.g. pushing a locally-authored post/alert up to a multidev). Meta values that look like ID references (`_thumbnail_id`, ACF relationship/image fields) are copied verbatim and **reported** — never silently remapped across databases.
 
 ### 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.
+- **Checksum-verified.** Every sync/clone 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.
@@ -119,18 +126,25 @@ TERMINUS_ENV=dev                   # default env (override per call)
 // 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 }
+// SYNC a front page's block markup onto the SAME post ID on production, verified
+{ "tool": "wp_sync_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 }
+// SYNC ALL meta for a post (full mirror) onto the same ID, verified
+{ "tool": "wp_sync_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",
+// SYNC only specific meta keys
+{ "tool": "wp_sync_post_meta", "post_id": 42, "from": "local", "to": "production",
   "keys": ["_thumbnail_id", "my_field"], "confirm": true }
+
+// CLONE a locally-authored post to production as a NEW post (returns new_id)
+{ "tool": "wp_clone_post", "post_id": 268529, "from": "local", "to": "production", "confirm": true }
+
+// Clone but force the new post to draft
+{ "tool": "wp_clone_post", "post_id": 268529, "from": "local", "to": "production",
+  "overrides": { "post_status": "draft" }, "confirm": true }
 ```
 
-Each copy returns `verified: true/false` with `src_md5` / `dst_md5`, the delivery mode, and per-side transport.
+`wp_sync_*` return `verified: true/false` with `src_md5` / `dst_md5`, the delivery mode, and per-side transport. `wp_clone_post` returns `new_id`, `verified`, `content_verified`, `meta_verified`, and `id_reference_keys` (meta keys to review).
 
 ## Debug logging
 
@@ -151,7 +165,7 @@ Failures (non-zero WP-CLI exits) are appended to a log in your system temp dir
 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).
+70 stdlib-only unit tests (split by area under `tests/`) cover config parsing, transport selection (local/Terminus/SSH), the argv size guard, newline handling, PHP-key safety, id-reference detection, and the full sync/clone/verify orchestration via an injectable command-runner seam (no real WP-CLI invoked).
 
 ## Releasing
 

{mcp_wp_cli_terminus-0.2.0 → mcp_wp_cli_terminus-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "mcp-wp-cli-terminus"
-version = "0.2.0"
+version = "0.3.0"
 description = "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."
 readme = "README.md"
 requires-python = ">=3.8"

{mcp_wp_cli_terminus-0.2.0 → mcp_wp_cli_terminus-0.3.0}/src/wp_cli_mcp/__init__.py

@@ -1,10 +1,10 @@
 #!/usr/bin/env python3
-"""wp_cli — a transport-agnostic WP-CLI MCP server package.
+"""wp_cli_mcp — 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.
+Exposes a stdio JSON-RPC MCP server with five tools:
+  wp_init_config, wp_cli, wp_sync_post, wp_sync_post_meta, wp_clone_post.
 
-Public API is re-exported here so callers (and tests) can `from wp_cli import ...`
+Public API is re-exported here so callers (and tests) can `from wp_cli_mcp import ...`
 without reaching into submodules.
 """
 
@@ -34,8 +34,9 @@ from .tools import (
     TOOL_DEFINITIONS,
     TOOL_REGISTRY,
     tool_wp_cli,
-    tool_wp_copy_post,
-    tool_wp_copy_post_meta,
+    tool_wp_sync_post,
+    tool_wp_sync_post_meta,
+    tool_wp_clone_post,
 )
 from .configure import tool_wp_init_config
 from .transport import (
@@ -54,7 +55,8 @@ __all__ = [
     "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_init_config", "tool_wp_cli", "tool_wp_copy_post", "tool_wp_copy_post_meta",
+    "tool_wp_init_config", "tool_wp_cli", "tool_wp_sync_post", "tool_wp_sync_post_meta",
+    "tool_wp_clone_post",
     "SERVER_NAME", "SERVER_VERSION", "PROTOCOL_VERSION",
     "handle_initialize", "handle_tools_call", "handle_tools_list", "main",
 ]

mcp_wp_cli_terminus-0.3.0/src/wp_cli_mcp/_shared.py

@@ -0,0 +1,142 @@
+#!/usr/bin/env python3
+"""Shared helpers used by the post sync/clone tools.
+
+Meta-map read/digest builders, destination-existence checks, post_content reads,
+and small result helpers. Stdlib only.
+"""
+
+import base64
+import hashlib
+import re
+from typing import List, Optional
+
+from .command import run_php_eval, run_wp
+
+# Meta keys travel as base64 data (never interpolated as raw PHP), but we still
+# constrain them defensively: a WP meta_key is a short identifier. This allow-list
+# accepts normal + protected keys (leading underscore, ACF field keys).
+_META_KEY_RE = re.compile(r"^[A-Za-z0-9_:.\-]+$")
+
+
+def _validate_from_to(from_, to):
+    for name, val in (("from", from_), ("to", to)):
+        if val not in ("local", "production"):
+            raise ValueError(f"'{name}' must be 'local' or 'production' (got {val!r}).")
+    if from_ == to:
+        raise ValueError("'from' and 'to' must differ — nothing to copy between the same env.")
+
+
+def _read_post_content(block, site_name, target, post_id, env):
+    """Return (ok, content_bytes, proc). `wp post get --field` appends exactly one
+    trailing newline to stdout that is NOT part of post_content — strip it so the
+    bytes (and their md5) match the value PHP strlen()/md5() see in the DB.
+    """
+    proc, _ = run_wp(
+        block, site_name, target,
+        ["post", "get", str(post_id), "--field=post_content"],
+        env, text=False,
+    )
+    if proc.returncode != 0:
+        return False, b"", proc
+    out = proc.stdout
+    if out.endswith(b"\r\n"):
+        out = out[:-2]
+    elif out.endswith(b"\n"):
+        out = out[:-1]
+    return True, out, proc
+
+
+def _dest_post_exists(block, site_name, target, post_id, env):
+    proc, _ = run_wp(
+        block, site_name, target,
+        ["post", "get", str(post_id), "--field=post_status"], env, text=True,
+    )
+    return proc.returncode == 0, proc
+
+
+def _keys_php_literal(keys):
+    """PHP array() of keys, each carried as base64_decode("...") so a key string
+    can never inject PHP (no interpolation, no quote breakout). Returns 'null' when
+    keys is None (meaning: all keys / full mirror)."""
+    if keys is None:
+        return "null"
+    parts = []
+    for k in keys:
+        kb = base64.b64encode(k.encode("utf-8")).decode("ascii")
+        parts.append('base64_decode("' + kb + '")')
+    return "array(" + ",".join(parts) + ")"
+
+
+def _meta_read_b64(block, site_name, target, post_id, env):
+    """(ok, b64, proc): the FULL raw meta map as base64(serialize(get_post_meta(id))).
+    Values are the raw stored DB strings (get_post_meta with no key does NOT
+    unserialize), so the payload is byte-faithful."""
+    php = (
+        '$m=get_post_meta(' + str(int(post_id)) + ');'
+        'if(!is_array($m)){$m=array();}'
+        'ksort($m);'
+        'echo base64_encode(serialize($m));'
+    )
+    proc, _, _ = run_php_eval(block, site_name, target, php, env, text=True)
+    if proc.returncode != 0:
+        return False, "", proc
+    return True, (proc.stdout or "").strip(), proc
+
+
+def _digest_php_from_b64(src_b64, keys):
+    """PHP that digests a serialized meta map (base64) restricted to `keys`,
+    canonicalized by ksort — used to digest the TRANSFERRED payload identically to
+    how the destination is digested. Echoes '<md5>|<bytes>'."""
+    return (
+        '$m=unserialize(base64_decode("' + src_b64 + '"));'
+        'if(!is_array($m)){$m=array();}'
+        '$only=' + _keys_php_literal(keys) + ';'
+        'if($only!==null){$f=array();foreach($only as $k){$f[$k]=array_key_exists($k,$m)?$m[$k]:null;}$m=$f;}'
+        'ksort($m);'
+        '$s=serialize($m);'
+        'echo md5($s)."|".strlen($s);'
+    )
+
+
+def _digest_php_from_db(post_id, keys):
+    """PHP that digests the LIVE meta of a post restricted to `keys` (ksort'd).
+    Same canonical form as _digest_php_from_b64 so the two are comparable."""
+    return (
+        '$m=get_post_meta(' + str(int(post_id)) + ');'
+        'if(!is_array($m)){$m=array();}'
+        '$only=' + _keys_php_literal(keys) + ';'
+        'if($only!==null){$f=array();foreach($only as $k){$f[$k]=array_key_exists($k,$m)?$m[$k]:null;}$m=$f;}'
+        'ksort($m);'
+        '$s=serialize($m);'
+        'echo md5($s)."|".strlen($s);'
+    )
+
+
+def _run_digest(block, site_name, target, php, env):
+    proc, _, _ = run_php_eval(block, site_name, target, php, env, text=True)
+    if proc.returncode != 0:
+        return False, "", 0, proc
+    out = (proc.stdout or "").strip()
+    if "|" not in out:
+        return False, "", 0, proc
+    md5_str, _, nbytes = out.partition("|")
+    try:
+        n = int(nbytes)
+    except ValueError:
+        n = 0
+    return True, md5_str, n, proc
+
+
+def _dec(v):
+    """Decode bytes stderr to str for JSON output."""
+    if isinstance(v, bytes):
+        return v.decode("utf-8", "replace")
+    return v
+
+
+def _err(message, site, post_id, from_, to, **extra):
+    d = {"verified": False, "error": message, "site": site, "post_id": post_id, "from": from_, "to": to}
+    d.update({k: v for k, v in extra.items() if v is not None})
+    return d
+
+

mcp_wp_cli_terminus-0.3.0/src/wp_cli_mcp/cli.py

@@ -0,0 +1,51 @@
+#!/usr/bin/env python3
+"""wp_cli — run an arbitrary WP-CLI command (local / Terminus / SSH)."""
+
+import shlex
+from typing import Optional
+
+from .config import guard_enabled, load_config, resolve_site
+from .command import is_destructive, run_wp, transport_label
+
+
+def tool_wp_cli(args: str, site: Optional[str] = None, target: str = "local", env: Optional[str] = None, confirm: bool = False) -> dict:
+    if target not in ("local", "production"):
+        raise ValueError(f"Invalid target '{target}'. Use 'local' or 'production'.")
+
+    arg_tokens = shlex.split(args)
+    if not arg_tokens:
+        raise ValueError("'args' is empty — provide a WP-CLI command (without 'wp').")
+    if arg_tokens[0] == "wp":
+        arg_tokens = arg_tokens[1:]
+        if not arg_tokens:
+            raise ValueError("'args' contained only 'wp' — provide a command.")
+
+    conf = load_config()
+    block = resolve_site(conf, site)
+    resolved_name = site or conf["globals"].get("DEFAULT_SITE", "") or sorted(conf["sites"])[0]
+
+    if target == "production" and guard_enabled(conf) and is_destructive(arg_tokens):
+        if not confirm:
+            return {
+                "blocked": True,
+                "reason": (
+                    "Destructive WP-CLI command blocked on production by PROD_GUARD. "
+                    "Re-run with confirm=true to proceed."
+                ),
+                "site": resolved_name,
+                "command": "wp " + " ".join(arg_tokens),
+                "target": target,
+            }
+
+    proc, full_cmd = run_wp(block, resolved_name, target, arg_tokens, env, text=True)
+
+    return {
+        "site": resolved_name,
+        "target": target,
+        "transport": transport_label(block, target),
+        "command": " ".join(shlex.quote(c) for c in full_cmd),
+        "exit_code": proc.returncode,
+        "stdout": proc.stdout,
+        "stderr": proc.stderr,
+    }
+

mcp_wp_cli_terminus-0.3.0/src/wp_cli_mcp/clone.py

@@ -0,0 +1,202 @@
+#!/usr/bin/env python3
+"""wp_clone_post — create a NEW post on the destination from a source post."""
+
+import base64
+import re
+from typing import Optional
+
+from .config import guard_enabled, load_config, resolve_site
+from .command import run_php_eval, transport_label
+from ._shared import _digest_php_from_db, _run_digest, _validate_from_to, _dec, _err
+
+
+_ID_REF_KEY_RE = re.compile(
+    r"(^_thumbnail_id$|_id$|^_?field_|(^|_)(post|page|attachment|image|gallery|"
+    r"relationship|parent|term|user|author)(_id)?s?$)",
+    re.IGNORECASE,
+)
+
+# Post fields carried when cloning (everything meaningful except the ID itself and
+# GUID, which the destination must own).
+_CLONE_FIELDS = [
+    "post_title", "post_content", "post_excerpt", "post_status", "post_type",
+    "post_name", "post_author", "post_date", "post_date_gmt", "post_parent",
+    "menu_order", "comment_status", "ping_status", "post_password", "post_mime_type",
+]
+
+
+def _clone_read_php(post_id: int) -> str:
+    """PHP that echoes '<base64(serialize([fields,meta]))>\\n<comma-separated META
+    keys>' for a post, or 'ERR:missing' if the post does not exist. The explicit
+    meta-key line lets us report ID-reference META keys precisely (no Python-side
+    guessing over the serialized blob). Byte-faithful: meta values are the raw
+    stored strings (no unserialize)."""
+    fields = ",".join('"' + f + '"' for f in _CLONE_FIELDS)
+    return (
+        '$p=get_post(' + str(int(post_id)) + ');'
+        'if(!$p){echo "ERR:missing";return;}'
+        '$f=array();foreach(array(' + fields + ') as $k){$f[$k]=$p->$k;}'
+        '$m=get_post_meta(' + str(int(post_id)) + ');if(!is_array($m)){$m=array();}ksort($m);'
+        'echo base64_encode(serialize(array("fields"=>$f,"meta"=>$m)))."\\n".implode(",",array_keys($m));'
+    )
+
+
+def _flag_id_ref_keys(meta_keys):
+    return sorted({k for k in meta_keys if _ID_REF_KEY_RE.search(k)})
+
+def tool_wp_clone_post(
+    post_id: int,
+    from_: Optional[str] = None,
+    to: Optional[str] = None,
+    site: Optional[str] = None,
+    from_env: Optional[str] = None,
+    to_env: Optional[str] = None,
+    overrides: Optional[dict] = None,
+    confirm: bool = False,
+    **kwargs,
+) -> dict:
+    """COPY a source post to another environment as a NEW post (dest assigns its ID).
+
+    Unlike wp_sync_post (which updates an existing same-ID post), this creates a
+    brand-new post on the destination from the source's fields + all meta, and
+    returns the new destination ID. Meta values that look like ID references are
+    copied verbatim and REPORTED (id_reference_keys) for manual remapping — no
+    silent remap. `overrides` may set/replace post fields on the new post (e.g.
+    {"post_status": "draft"}). Content/meta never pass through the caller's text.
+    """
+    if from_ is None:
+        from_ = kwargs.get("from")
+    _validate_from_to(from_, to)
+    if not isinstance(post_id, int) or post_id <= 0:
+        raise ValueError(f"'post_id' must be a positive integer (got {post_id!r}).")
+    if overrides is not None and not isinstance(overrides, dict):
+        raise ValueError("'overrides' must be an object of post field -> value.")
+
+    conf = load_config()
+    block = resolve_site(conf, site)
+    resolved_name = site or conf["globals"].get("DEFAULT_SITE", "") or sorted(conf["sites"])[0]
+
+    if to == "production" and guard_enabled(conf) and not confirm:
+        return {
+            "blocked": True,
+            "reason": (
+                "wp_clone_post creates a new post on a PRODUCTION destination, blocked by "
+                "PROD_GUARD. Re-run with confirm=true to proceed."
+            ),
+            "site": resolved_name, "post_id": post_id, "from": from_, "to": to,
+        }
+
+    # 1. Read source fields + raw meta as one base64 payload, plus the explicit list
+    #    of META key names (second line) for a precise id-reference report.
+    try:
+        rp, _, _ = run_php_eval(block, resolved_name, from_, _clone_read_php(post_id), from_env, text=True)
+    except Exception as e:
+        return _err(str(e), resolved_name, post_id, from_, to)
+    out = (rp.stdout or "").strip()
+    if rp.returncode != 0 or not out or out.startswith("ERR:"):
+        return _err(f"Failed to read source post {post_id} (missing or unreadable).",
+                    resolved_name, post_id, from_, to, exit_code=rp.returncode,
+                    stderr=_dec(rp.stderr))
+    src_b64, _, meta_keys_line = out.partition("\n")
+    src_b64 = src_b64.strip()
+    source_meta_keys = [k for k in meta_keys_line.strip().split(",") if k]
+
+    # 2. Create the post on the destination from the transferred payload, then write
+    #    all meta into the new post. wp_insert_post assigns the new ID. Overrides are
+    #    applied over the source fields. Returns "OK:<new_id>".
+    ov_php = "array()"
+    if overrides:
+        parts = []
+        for k, v in overrides.items():
+            kb = base64.b64encode(str(k).encode("utf-8")).decode("ascii")
+            vb = base64.b64encode(str(v).encode("utf-8")).decode("ascii")
+            parts.append('base64_decode("' + kb + '")=>base64_decode("' + vb + '")')
+        ov_php = "array(" + ",".join(parts) + ")"
+    create_php = (
+        '$d=unserialize(base64_decode("' + src_b64 + '"));'
+        'if(!is_array($d)||!isset($d["fields"])){echo "ERR:bad payload";return;}'
+        '$f=$d["fields"];$ov=' + ov_php + ';foreach($ov as $k=>$v){$f[$k]=$v;}'
+        # Never carry an ID/GUID; let WP assign them.
+        'unset($f["ID"]);unset($f["guid"]);'
+        '$new=wp_insert_post($f,true);'
+        'if(is_wp_error($new)){echo "ERR:".$new->get_error_message();return;}'
+        # Write meta verbatim (maybe_unserialize so WP re-serializes to the same bytes).
+        '$m=isset($d["meta"])&&is_array($d["meta"])?$d["meta"]:array();'
+        'foreach($m as $k=>$vals){delete_post_meta($new,$k);foreach($vals as $v){add_post_meta($new,$k,maybe_unserialize($v));}}'
+        'echo "OK:".$new;'
+    )
+    try:
+        cp, _, mode = run_php_eval(block, resolved_name, to, create_php, to_env, text=True)
+    except Exception as e:
+        return _err(str(e), resolved_name, post_id, from_, to)
+    cout = (cp.stdout or "").strip()
+    if cp.returncode != 0 or not cout.startswith("OK:"):
+        return _err("Clone failed on destination (wp_insert_post or meta write).",
+                    resolved_name, post_id, from_, to, exit_code=cp.returncode,
+                    stdout=cp.stdout, stderr=_dec(cp.stderr), delivery=mode)
+    try:
+        new_id = int(cout.split("OK:", 1)[1].strip())
+    except (ValueError, IndexError):
+        return _err(f"Clone succeeded but could not parse new ID from: {cout!r}",
+                    resolved_name, post_id, from_, to)
+
+    # 3. Verify: compare source vs new-post content md5, and source meta digest vs
+    #    the new post's meta digest. Both computed in PHP.
+    # content md5 (source from payload vs destination live)
+    content_php = (
+        '$d=unserialize(base64_decode("' + src_b64 + '"));'
+        '$src=isset($d["fields"]["post_content"])?$d["fields"]["post_content"]:"";'
+        '$dst=get_post(' + str(new_id) + ')->post_content;'
+        'echo md5($src)."|".md5($dst);'
+    )
+    content_ok = False
+    cvp, _, _ = run_php_eval(block, resolved_name, to, content_php, to_env, text=True)
+    cvo = (cvp.stdout or "").strip()
+    if cvp.returncode == 0 and "|" in cvo:
+        a, _, b = cvo.partition("|")
+        content_ok = (a == b)
+
+    # meta digest: source payload meta vs new-post live meta
+    src_meta_digest = _digest_php_from_b64_meta(src_b64)
+    s_ok, src_dig, _sn, _sp = _run_digest(block, resolved_name, to, src_meta_digest, to_env)
+    d_ok, dst_dig, _dn, _dp = _run_digest(block, resolved_name, to, _digest_php_from_db(new_id, None), to_env)
+    meta_ok = (s_ok and d_ok and src_dig == dst_dig)
+
+    # id-reference META keys (from the source meta key list) for manual review
+    id_ref_keys = _flag_id_ref_keys(source_meta_keys)
+
+    verified = content_ok and meta_ok
+    result = {
+        "verified": verified,
+        "cloned": True,
+        "new_id": new_id,
+        "source_post_id": post_id,
+        "site": resolved_name, "from": from_, "to": to,
+        "content_verified": content_ok,
+        "meta_verified": meta_ok,
+        "id_reference_keys": id_ref_keys,
+        "delivery": mode,
+        "from_transport": transport_label(block, from_),
+        "to_transport": transport_label(block, to),
+    }
+    if id_ref_keys:
+        result["note"] = (
+            "The listed meta keys hold ID references that point at the SOURCE database and "
+            "likely need manual remapping on the destination (their IDs differ across envs)."
+        )
+    if not verified:
+        result["error"] = (
+            "Clone written but verification failed "
+            f"(content_verified={content_ok}, meta_verified={meta_ok}). Investigate the new "
+            f"post {new_id} before trusting it."
+        )
+    return result
+
+
+def _digest_php_from_b64_meta(src_b64: str) -> str:
+    """Digest the meta map inside a clone payload (base64(serialize({fields,meta})))."""
+    return (
+        '$d=unserialize(base64_decode("' + src_b64 + '"));'
+        '$m=isset($d["meta"])&&is_array($d["meta"])?$d["meta"]:array();'
+        'ksort($m);$s=serialize($m);echo md5($s)."|".strlen($s);'
+    )