78 lines
4.6 KiB
Markdown
78 lines
4.6 KiB
Markdown
# WP Browser
|
||
|
||
Use this skill for WordPress tasks that require a real browser instead of WP-CLI or file inspection. Prefer `references/wp-project.md` first when you need to resolve a project slug, local URL, production URL, repo, or paths.
|
||
|
||
## Safety and scope
|
||
|
||
- Treat local sites as safe to inspect and operate, but still avoid destructive admin actions unless explicitly requested.
|
||
- Ask before changing production content, settings, users, plugins, themes, orders, forms, menus, options, or publishing state.
|
||
- Prefer read-only checks on remote/production sites: navigate, inspect, screenshot, verify text/layout, check console/network symptoms.
|
||
- Do not submit public forms, checkout flows, newsletter signups, contact forms, or anything that sends email/external effects unless explicitly requested.
|
||
- If login is required, use existing browser session/cookies when available. Ask for credentials only if no usable session exists.
|
||
|
||
## Choosing the URL
|
||
|
||
Resolve the target URL from the request:
|
||
|
||
- If the user gives a full URL, use it directly.
|
||
- If the user gives a project slug, use `references/wp-project.md` conventions to derive the local site URL: `${WEBSIMPLE_STACK_PROTOCOL}://${slug}.${WEBSIMPLE_STACK_DOMAIN}`.
|
||
- If the user says production/remote, prefer `WP_SITE_URL` from Gitea repository Actions variables via `references/websimple-gitea.md` conventions/tools when available.
|
||
- If the request is ambiguous between local and production, default to local and state that assumption briefly.
|
||
|
||
## Browser environment prerequisite
|
||
|
||
Websimple local dev sites may resolve to private network IPs, for example a `*.${WEBSIMPLE_STACK_DOMAIN}` hostname resolving to an IPv6 ULA address like `fd00::/8`. Some browser/MCP harnesses are SSRF-guarded and block private-network targets by default.
|
||
|
||
If browser navigation to a local Websimple site fails with a policy-related error (e.g. "navigation blocked by policy"), the browser harness likely needs an allowlist entry for the local Websimple domain plus private-network opt-in. The shape of that configuration depends on the harness in use (Playwright MCP, OpenClaw, etc.), but conceptually:
|
||
|
||
- Allow `*.${WEBSIMPLE_STACK_DOMAIN}` (and `${WEBSIMPLE_STACK_DOMAIN}` itself) on the hostname allowlist.
|
||
- Permit private-network destinations.
|
||
|
||
Resolve `${WEBSIMPLE_STACK_DOMAIN}` from the environment; do not hard-code a specific local domain. Prefer an allowlisted form over globally allowing private-network access. Restart/reload the browser harness after changing its SSRF policy.
|
||
|
||
## Browser workflow
|
||
|
||
1. Open or reuse a browser tab for the target site.
|
||
2. Take a snapshot before interacting; use semantic/ARIA refs where possible.
|
||
3. Navigate like a user: click links/buttons, fill inputs, use menus, and wait for reliable UI state instead of arbitrary delays.
|
||
4. Check the page result with at least one concrete signal: visible text, URL, status page, screenshot, console messages, or DOM state.
|
||
5. Report concise evidence: URL checked, action performed, result, and any blockers.
|
||
|
||
For multi-step browser flows, login checks, stale refs, or tab recovery, follow the general `browser-automation` skill’s browser-control practices.
|
||
|
||
## WordPress admin
|
||
|
||
Common admin URLs:
|
||
|
||
- Dashboard: `/wp-admin/`
|
||
- Login: `/wp-login.php`
|
||
- Plugins: `/wp-admin/plugins.php`
|
||
- Themes: `/wp-admin/themes.php`
|
||
- Customizer: `/wp-admin/customize.php`
|
||
- Menus: `/wp-admin/nav-menus.php`
|
||
- Pages: `/wp-admin/edit.php?post_type=page`
|
||
- Posts: `/wp-admin/edit.php`
|
||
- Site Health: `/wp-admin/site-health.php`
|
||
|
||
When checking admin screens:
|
||
|
||
- Confirm whether the session is authenticated by looking for the admin bar, dashboard, or login form.
|
||
- Avoid saving forms unless requested.
|
||
- For settings screens, inspect current values and controls before editing.
|
||
- For editor screens, avoid autosave-risky content edits unless explicitly requested.
|
||
- If normal browser `fill` does not populate the WordPress login fields, use a narrow DOM fallback to set `#user_login` and `#user_pass`, dispatch `input` events, then submit. Do not echo credentials back to the user.
|
||
|
||
## Frontend checks
|
||
|
||
For frontend verification:
|
||
|
||
- Check desktop first unless the user asks for mobile/responsive.
|
||
- Capture a screenshot when visual appearance matters.
|
||
- Inspect console errors when behavior looks broken or JavaScript-heavy.
|
||
- Verify canonical symptoms with user-visible evidence, not assumptions from source code alone.
|
||
|
||
## Cookies and debugging hooks
|
||
|
||
- For Xdebug-specific browser requests, use `references/wp-xdebug.md`.
|
||
- If needed manually, set or include the `XDEBUG_SESSION=vscode` cookie only for local debugging flows and mention that it may route PHP through `wp-php-xdebug`.
|