claude-websimple-devops/references/wp-local-site.md

# WP Local Site

Use this skill for local WordPress site lifecycle operations. For project naming and derived values, use `references/wp-project.md`. For stack/host environment assumptions, use `references/websimple-stack.md`. For Composer-managed plugins/themes, use `references/wp-composer.md`.

## Derived values

For project slug `${slug}`, use `references/wp-project.md` conventions:

- Local project path: `${WP_LOCAL_ROOT_PATH}/${slug}`
- Local database name: `wp_${slug}`
- Local site URL: `${WEBSIMPLE_STACK_PROTOCOL}://${slug}.${WEBSIMPLE_STACK_DOMAIN}`
- Default local DB table prefix: `wp_`, unless the production/source instance uses a different prefix
- Repository URL: `https://gitea.websimple.com/wp-sites/${slug}`

Resolve project values with `references/wp-project.md`; do not hard-code local paths, protocol, or domain.

## Safety

- Prefer read-only checks before creating, deleting, or resetting anything.
- Ask before destructive actions such as dropping a database, deleting a project directory, or overwriting local files.
- Use recoverable deletion where practical. If shelling out, prefer moving to the user's trash over permanent removal.
- Never delete source-controlled project-specific plugins/themes as part of Composer repair; use the `references/wp-composer.md` integrity guidance.
- Treat remote hosts as read-only unless a future approved workflow says otherwise.

## Create local site skeleton

A local site creation workflow should generally:

1. Resolve `${slug}` and derived values with `references/wp-project.md`.
2. Verify `${WP_LOCAL_ROOT_PATH}` exists.
3. Verify `${WP_LOCAL_ROOT_PATH}/${slug}` does not already exist, or ask how to proceed.
4. Clone or create the project directory from `https://gitea.websimple.com/wp-sites/${slug}`.
5. Create the local database `wp_${slug}` using host `mysql` credentials from `~/.my.cnf`.
6. Determine the DB table prefix: use `wp_` by default, or the production/source prefix when provisioning from an existing site.
7. Run `wp core config` with only the database name and table prefix when WP-CLI defaults provide DB host/user/password.
8. Run Composer install if the project uses Composer.
9. Either run `wp core install` for a fresh local site or synchronize/import from an existing remote site.
10. Verify local URL and WP-CLI access.

Example database creation command:

```bash
mysql -e 'CREATE DATABASE `wp_example` DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;'
```

Use the real derived DB name; quote identifiers safely.

## WP core config

The host should have WP-CLI defaults in `~/.wp-cli/config.yml` for DB host, user, and password. Local provisioning should normally only specify the DB name:

```bash
wp core config --dbname="wp_${slug}" --dbprefix="wp_"
```

Run from the local project path. Do not duplicate DB host/user/password flags unless defaults are missing or the user explicitly asks.

Use `wp_` as the default table prefix for new local sites. When provisioning from production/staging, detect and preserve the source table prefix if it differs from `wp_`; the imported database and local `wp-config.php` prefix must agree.

## WP core install

Use `wp core install` only when creating a fresh local site without importing an existing database. Do not run it before a remote DB import because the import will replace the local tables anyway.

Example for a new local site:

```bash
wp core install \
  --url="${WEBSIMPLE_STACK_PROTOCOL}://${slug}.${WEBSIMPLE_STACK_DOMAIN}" \
  --title="${slug}" \
  --skip-email
```

`~/.wp-cli/config.yml` contains default admin user, email, and password values, so do not pass `--admin_user`, `--admin_email`, or `--admin_password` unless the user asks for custom values. Avoid inventing real production credentials.

## Standard admin user

Local sites should have the standard admin user from `~/.wp-cli/config.yml`. After installing or importing a site, check whether that user exists. If missing, create it using the configured default admin values.

Do not hard-code admin credentials in commands. Do not echo the password in chat or log summaries. Refer to credentials by variable name only.

The exact YAML shape varies by user setup. Inspect the file before constructing any command, so the keys you read match the keys that actually exist:

```bash
# Inspect — show keys only, not the password value
grep -E '^[[:space:]]*(user_login|user_email|user_pass|role)' ~/.wp-cli/config.yml \
  | sed 's/\(user_pass:\).*/\1 <redacted>/'
```

Two common shapes:

```yaml
# Shape A — defaults nested under `user create:`
user create:
  user_login: someuser
  user_email: someone@example.com
  user_pass: <set>
  role: administrator
```

```yaml
# Shape B — flat top-level keys consumed by custom commands
admin_user: someuser
admin_email: someone@example.com
admin_password: <set>
```

If the file uses Shape A, WP-CLI will already apply the defaults when `wp user create` runs without explicit flags. If it uses Shape B, the values have to be passed explicitly.

When `yq` is available, prefer it over hand-parsing:

```bash
ADMIN_USER="$(yq '.["user create"].user_login // .admin_user' ~/.wp-cli/config.yml)"
ADMIN_EMAIL="$(yq '.["user create"].user_email // .admin_email' ~/.wp-cli/config.yml)"
# Keep ADMIN_PASSWORD only in the subshell that needs it; do not export or print it.
```

If `yq` is not available and the YAML doesn't match a known shape, ask the user for the admin login and email rather than guessing — and have them provide the password via stdin (`read -s`) instead of an argument that would land in shell history.

Typical flow:

1. Inspect `~/.wp-cli/config.yml` and identify the admin user/email key names actually used.
2. Check whether that user exists locally.
3. Create the user only if missing.
4. Grant the administrator role if needed.

```bash
# Step 2–4 — assuming ADMIN_USER, ADMIN_EMAIL, ADMIN_PASSWORD are set in the current shell
if ! wp user get "$ADMIN_USER" >/dev/null 2>&1; then
    wp user create "$ADMIN_USER" "$ADMIN_EMAIL" \
        --role=administrator \
        --user_pass="$ADMIN_PASSWORD"
fi
wp user set-role "$ADMIN_USER" administrator
```

If `wp user create` works without the explicit `--user_pass` flag (Shape A in use), prefer that form so the password never appears on the command line.

## Synchronize from remote site

Synchronizing from a remote site means pulling production/staging state into the local site. Keep remote actions read-only: export/read/copy from remote is okay; writing to or mutating remote is not.

Typical flow:

1. Resolve local metadata with `references/wp-project.md` and remote metadata with `references/websimple-gitea.md` Actions variables, especially `WP_SITE_URL`.
2. Confirm source remote URL/host and destination local path/database.
3. Create/reset the local database only after confirmation.
4. Detect the remote/source DB table prefix before export/import. Use `wp_` only if the source also uses `wp_` or the source prefix is unknown and no imported DB is involved.
5. Export the remote database in a read-only way, preferably streaming to local instead of leaving files on the remote host.
6. Import into local DB.
7. Ensure local `wp-config.php` uses the same table prefix as the imported DB.
8. Search-replace remote URLs to the derived local URL.
9. Pull uploads/media from remote unless specified otherwise.
10. Verify `siteurl` and `home` locally.

Preferred DB sync path: stream a compressed remote DB dump over SSH into the local MySQL client. Use this when both remote WP-CLI and local `mysql` are available:

```bash
ssh "$REMOTE_SSH" 'cd "$REMOTE_PATH" && wp db export - --skip-plugins --skip-themes --single-transaction --quick --lock-tables=false | gzip -c' \
  | gunzip \
  | mysql "$LOCAL_DB_NAME"
```

After DB import, run URL replacement locally:

```bash
wp search-replace "$REMOTE_SITE_URL" "${WEBSIMPLE_STACK_PROTOCOL}://${slug}.${WEBSIMPLE_STACK_DOMAIN}" --all-tables --skip-columns=guid
wp option get siteurl
wp option get home
```

Do not run `wp search-replace` on the remote site during local synchronization.

Preferred uploads sync path: use `rsync` over SSH and include `--delete` so local `wp-content/uploads/` matches remote exactly, unless the user asks to preserve extra local files. Websimple SSH usually requires an explicit port, so include the SSH transport option when needed:

```bash
rsync -az --delete -e "ssh -p $REMOTE_SSH_PORT" "$REMOTE_SSH:$REMOTE_PATH/wp-content/uploads/" "wp-content/uploads/"
```

If the SSH host alias already encodes the port in `~/.ssh/config`, the `-e "ssh -p ..."` option may be omitted. If remote uploads path differs, inspect the project before syncing. Be explicit when `--delete` will remove local-only upload files.

## Provision from existing project

When provisioning from an existing local or remote project:

1. Resolve local and remote metadata using `references/wp-project.md` and `references/websimple-gitea.md`.
2. Confirm the source and destination clearly.
3. Keep remote actions read-only.
4. Import database/content only after confirming the target local DB and path.
5. After import, replace remote URLs with the derived local site URL.
6. Run small verification checks, such as `wp option get siteurl` and `wp option get home`.

## Delete/reset local site

A local delete/reset workflow may include:

- local project directory `${WP_LOCAL_ROOT_PATH}/${slug}`
- local database `wp_${slug}`
- generated/cache artifacts

Before deleting:

1. Show the resolved path, DB name, and local URL.
2. Check whether the path exists and whether it has uncommitted Git changes.
3. Ask for confirmation.
4. Prefer backup/trash for files where practical.
5. Drop the local DB only after explicit confirmation.

Example DB drop command after confirmation:

```bash
mysql -e 'DROP DATABASE `wp_example`;'
```

Use the real derived DB name; quote identifiers safely.