wp-connect

WP Connect

Re-open a previously paired site, or open a new connection over local/SSH/Docker. Picks the right connect_* tool by what the user has and what they need to do.

Iron Rule

1. NEVER pick a connection kind without knowing what the user will DO — REST works for 58 of 62 tools but Local/SSH/Docker are needed for the wp-cli-via-companion-shortcut bypass (rare) and direct filesystem ops outside ABSPATH. 2. NEVER store the chosen kind silently — surface "I'm opening this as a `` target because " so the user can correct mid-flow. 3. ALWAYS close the previous target with `rolepod_wp_disconnect` before opening the same site under a different kind — registry collisions cause confusing tool failures later.

When to use

• "เชื่อม walnutztudio.com" + creds are already in vault (skip pair).
• User wants to work against a local WordPress at /path/to/wp/.
• User has SSH access to the server and wants direct shell.
• User runs WP-in-Docker locally.

Skip when:

• No creds in vault AND user pasted a pair prompt → wp-pair-setup.
• User already has an active target_id → no need to reconnect.

Boundary

Owns:

• Picking the kind (local / rest / ssh / docker).
• Calling the right rolepod_wp_connect_<kind> tool.
• Surfacing the resulting target_id + companion status.

Does not own:

• Pairing (first-time companion redeem) → wp-pair-setup.
• Post-connect health probe — that is wp-health-check.
• Any actual WP operation — pick the right next skill.

Return / hand off:

• REST + no creds → wp-pair-setup for one-click OR manual App Password entry.
• Connection opens but companion missing → wp-health-check for full report.

Inputs to gather

• siteurl (REST) OR filesystem path (Local) OR host:user (SSH) OR container_name (Docker).
• For SSH: SSH key path / port if non-default.
• For Docker: container name / wp-cli command path inside container.
• (optional) require_companion: true if the user explicitly needs power tools.

Workflow

1. Pick the kind

Read references/connect-kinds.md if unsure. Quick rule:

User has	Pick
siteurl + App Password (any host, including shared)	rest
filesystem path to wp-config.php	local
SSH access to server	ssh
WP in Docker on this machine	docker

Default to REST unless the user explicitly says otherwise — it works on every host.

2. Open

Call the matching tool:

• rolepod_wp_connect_rest { url, [credential_ref], [require_companion] }
• rolepod_wp_connect_local { path }
• rolepod_wp_connect_ssh { host, user, [keyPath], [port] }
• rolepod_wp_connect_docker { containerName, [wpCliPath] }

3. Surface state

Tell user: kind + target_id + wp_version + companion presence + any warnings.

4. Hand off

If user already said what to do → hand off immediately. Otherwise ask.

If a matching Rolepod agent is available

• rolepod:devops-sre for SSH key / Docker config issues.
• rolepod:backend-developer for follow-up REST work.

If no matching agent is available

Execute as Lead:

1. Read what the user has.
2. Pick a kind (REST is default).
3. Call the right connect_*.
4. Surface target_id + warnings.
5. Hand off.

Output

No durable artifact. The opened target lives in the in-memory TargetRegistry for this session.

Examples

No examples file. Kind selection is single-decision and the workflow is one tool call.

References

Load when the user's situation does not match the quick rule:

• references/connect-kinds.md — which kind for which scenario; trade-offs around companion availability, security guarantees, and performance.

Hard stops

• CREDENTIALS_MISSING on REST → STOP. Hand off to wp-pair-setup (recommended) or instruct manual rolepod-wplab credentials add <site>.
• REST_AUTH_FAILED on a previously-working site → STOP. The App Password was revoked from profile.php. Hand off to wp-pair-setup.
• require_companion=true but companion: null → STOP. Tell user to install the WP plugin via wp plugin install https://github.com/nuttaruj/rolepod-wp/releases/latest/download/rolepod-wp.zip --activate.
• HTTP, not HTTPS → STOP. RestTarget refuses non-https URLs unconditionally.

Full Rolepod enhancement

Full Rolepod adds an auto-reconnect path that detects an expired session token mid-flow and silently re-handshakes; standalone, the user sees a single retryable error.

Next phase

• wp-health-check for a fuller report after open.
• The skill matching the user's original ask (wp-content, wp-edit-*, wp-scaffold, wp-diagnose, wp-execute-php).