@rolepod/wplab 1.2.1

package/.claude-plugin/plugin.json

@@ -0,0 +1,21 @@
+{
+  "name": "rolepod-wplab",
+  "displayName": "Rolepod WPLab",
+  "version": "0.1.0",
+  "description": "Multi-target WordPress automation for AI agents — scaffold, audit, verify, safe ops via wp-cli + REST + scoped fs. Optional companion plugin unlocks execute-php + runtime introspection. MIT, rolepod ecosystem.",
+  "author": {
+    "name": "nuttaruj",
+    "url": "https://github.com/nuttaruj"
+  },
+  "homepage": "https://github.com/nuttaruj/rolepod-wplab",
+  "repository": "https://github.com/nuttaruj/rolepod-wplab",
+  "license": "MIT",
+  "keywords": [
+    "mcp",
+    "wordpress",
+    "wp-cli",
+    "automation",
+    "rolepod",
+    "ai-agents"
+  ]
+}

package/CHANGELOG.md

@@ -0,0 +1,394 @@
+# Changelog
+
+All notable changes to `@rolepod/wplab` are documented here. Follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) format and [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.2.1] — 2026-05-26 — Path-2 polish
+
+### Changed
+
+- `rolepod_wp_connect_rest` `CREDENTIALS_MISSING` error now lists BOTH paths (companion Quick Start URL + manual `credentials add` command) so the AI can guide the user without guessing.
+- `RestTarget.open` `REST_AUTH_FAILED` error includes the same two-path suggestion plus the setup-wizard URL on the target host.
+- Both errors carry `setup_wizard_url` in `meta` for AI agents that prefer structured data over message text.
+
+### Numbers
+
+- MCP tools: **62** (unchanged).
+- Tests: 141 passing.
+
+## [1.2.0] — 2026-05-26 — One-click pair (Novamira-style setup UX)
+
+### Added
+
+- `rolepod_wp_pair { siteurl, pair_token }` — single MCP call that redeems a companion-issued pair token for a real WP Application Password (companion-minted under the issuing admin's user, named `wplab-pair-<timestamp>`). Stores credential in vault + opens a `RestTarget` in one shot.
+- Companion endpoint **POST `/wp-json/wplab/v1/pair/generate`** (admin only, manage_options) — issues a 256-bit pair token, TTL 60 min, max 5 active per admin.
+- Companion endpoint **POST `/wp-json/wplab/v1/pair/redeem`** (public, token-authed) — atomic single-use redeem; per-IP throttle (10 failed / hour).
+- Companion `src/Security/PairToken.php` — SHA-256 hashed-at-rest tokens in `wp_options`, opportunistic sweep of expired rows.
+- Companion `Tools → WPLab Setup` page extended with **"⚡ Quick Start"** section: button → mints pair token → renders ready-to-paste prompt that includes Claude Code / Cursor / Codex / Gemini install snippets + `rolepod_wp_pair` call with siteurl + pair_token baked in. One-click copy.
+- New skill `skills/wp-pair-setup/SKILL.md` — instructs AI agents on the pair flow + failure modes + security notes.
+
+### Schema additions
+
+- `PairInputSchema` — siteurl https-only refine + pair_token regex `/^wplab_pair_[a-f0-9]{48}$/`.
+- `PairOutputSchema` — target_id + siteurl + username + capabilities + companion_version + is_production + app_password_name + credential_stored.
+
+### Security
+
+- Pair token = SHA-256 hashed at rest, never returned by any GET endpoint.
+- Single-use guarantee: `PairToken::redeem` deletes the wp_options row **before** acting on the payload — concurrent redeem attempts can't both succeed.
+- TTL 60 min, post-redeem the App Password is the long-lived credential (revocable from `profile.php`).
+- Pair generate requires admin (`manage_options`). Pair redeem rate-limited per IP via transient.
+- App Password name `wplab-pair-<UTC-timestamp>` makes attribution + revocation trivial.
+- Production guard unchanged — pair-minted credentials are subject to all the same `ProdGuard` checks on power tools.
+- Companion `endpoints_enabled` master toggle still applies — pair endpoints respect it.
+
+### Numbers
+
+- **MCP tools**: 61 → 62 (+1: `rolepod_wp_pair`).
+- **Companion REST endpoints**: 8 → 10 (+2: pair/generate, pair/redeem).
+- **Skills**: 10 → 11 (+1: wp-pair-setup).
+- **Unit + smoke tests**: 134 → 141 (+7 PairInput/Output schema tests).
+
+### Notes
+
+- Schema-freeze policy honored: every change is additive (new tool, new schemas, new endpoints).
+- Companion-first install path is now the recommended quick-start. Manual setup path (App Password + npm install + claude mcp add + credentials add) preserved on the same wizard page for users on CLIs without a wplab plugin.
+
+## [1.1.0] — 2026-05-26 — Parity + lead expansion (Tier A/B/C/D)
+
+### Added — Tier A (close Novamira gaps)
+
+- `rolepod_wp_divi_read` / `rolepod_wp_divi_write` — Divi Builder pages (post_content shortcodes + `_et_pb_use_builder` flag).
+- `rolepod_wp_oxygen_read` / `rolepod_wp_oxygen_write` — Oxygen Builder (`ct_builder_shortcodes` post meta).
+- `rolepod_wp_bricks_write` — extends Bricks adapter with page / header / footer element-tree writes.
+- `rolepod_wp_yoast_write` — Yoast SEO post meta (focus_keyword / meta_description / title / canonical / noindex).
+- `rolepod_wp_rankmath_write` — Rank Math SEO post meta (mirrors Yoast surface).
+- `rolepod_wp_wpml_write` — set_post_language / link_translations / duplicate_for_translation ops.
+
+### Added — Tier B (exceed Novamira surface)
+
+- `rolepod_wp_forms_read` / `rolepod_wp_forms_write` — unified Gravity / Contact Form 7 / WPForms adapter with auto-detect.
+- `rolepod_wp_cron_tool` — list / run / delete WP-Cron events.
+- `rolepod_wp_cache_tool` — inspect object cache + transient counts; flush_object / flush_transients ops.
+- `rolepod_wp_mail_test` — send test email via wp_mail() (companion execute-php preferred, wp-cli `wp eval` fallback).
+- `rolepod_wp_clone` — composite: db export+import + wp-content sync + url search-replace + plugin version sync.
+- `rolepod_wp_backup_create` / `rolepod_wp_backup_restore` — db dump + wp-content manifest snapshots.
+
+### Added — Tier C (setup UX parity)
+
+- `rolepod-wplab init` — interactive 5-step wizard (App Password + REST probe + handshake + credential store + starter profile).
+- `rolepod-wplab companion install --target=<host>` — probe + emit copy-paste wp-cli installer command.
+- `rolepod-wplab companion status --target=<host>` — handshake check + capability dump.
+- Companion plugin: new **Tools → WPLab Setup** wizard page with App Password + MCP install copy-paste blocks.
+
+### Added — Tier D (moat extend)
+
+- `rolepod_wp_user_session_list` — enumerate active user sessions via `wp_usermeta.session_tokens` (security audit).
+- `rolepod_wp_rest_dump` — enumerate every registered REST route (optional `filter_namespace`).
+- `rolepod_wp_scaffold_pattern` — scaffolds a block pattern PHP file inside a theme or plugin.
+- `rolepod_wp_diagnose` — non-destructive sweep: plugin_conflict_probe / slow_queries / large_options / broken_images / php_errors.
+
+### Changed
+
+- `AllowList.ts` — added wp-cli READ_ONLY entries: `transient list`, `cache type`, `user session list`.
+- `AllowList.ts` — added wp-cli DESTRUCTIVE entries: `cron event run` / `delete` / `schedule`, `cache flush`, `transient delete` / `delete-expired`, `db export` / `import`, `search-replace`, `wpml`, `gf`, `user session destroy`.
+- `tests/smoke/mcp-handshake.test.ts` — expected tool count 41 → 61.
+
+### Numbers
+
+- **MCP tools**: 41 → 61 (+20).
+- **Adapters**: 8 (Elementor / Woo / ACF / Bricks / WPML / Yoast / RankMath) + 3 new dir (Divi / Oxygen / Forms).
+- **CLI subcommands**: 5 → 7 (added `init`, `companion`).
+- **Companion REST endpoints**: 8 (unchanged).
+- **Unit + smoke tests**: 117 passing.
+
+### Notes
+
+- Schema-freeze policy honored: every new tool is **additive** (new tool names). No existing input/output schema fields changed.
+- Forms adapter `list_entries` is wired for Gravity Forms in v1.1; CF7 / WPForms entries land in plugin-private tables — adapter returns empty for those scopes in v1.1 (planned for v1.2 once both expose entry REST routes consistently).
+- `wp_clone` `wp_content` scope copies top-level entries only — full deep tree sync (large media) is deferred to v1.2 with a companion `fs-rsync` endpoint.
+- `wp_backup_restore` `wp_content` scope is manifest-verify only in v1.1; deep restore requires batch fs-write API (v1.2).
+
+## [1.0.0] — 2026-05-25 — Stable (schema-frozen)
+
+### Schema-freeze promise
+
+All MCP tool **names** and **required input fields** locked. Breaking changes require a **major bump**. Adding optional input fields, adding output fields, adding new tools = minor. Bug fixes + dep bumps = patch.
+
+The frozen schema:
+- **46 MCP tools** with `rolepod_wp_*` prefix (connect + lifecycle + atomic + typed CRUD + adapters + composites + memory + companion-gated power).
+- Schema source: `src/schema/tools.ts` (zod). Exported to `dist/schemas/tools.json` on build.
+- Replay bundle format `v1` (`src/bin/replay.ts`).
+- Companion REST namespace `/wp-json/wplab/v1/` with 8 endpoints.
+
+### Locked
+
+- Tool names + required fields.
+- Profile names: strict / personal / power.
+- Target kinds: local / rest / ssh / docker.
+- Allow-list categories + never-allowed list (W-005).
+- Filesystem scope rules (W-006).
+- DB SELECT-only guard (W-007).
+- Production guard semantics (W-008).
+- Credential vault layout (W-018).
+- Memory directory layout (W-028).
+- Replay bundle JSON shape.
+
+### Not locked
+
+- Internal Target interface methods may grow (additive only).
+- Composite implementations may improve.
+- Adapter slate may expand (new plugins post-v1.0 are minor bumps).
+- Companion v1.0+ may add new endpoints (additive).
+
+### Pairs with
+
+- `rolepod-wplab-companion` **v1.0** — schema-frozen alongside; audit log format frozen, capability map locked.
+
+### Maintainer next actions (post-tag)
+
+- npm publish `@rolepod/wplab`.
+- Submit `rolepod-wplab-companion` to wordpress.org plugin directory (gated on WP review).
+- External security audit per `SECURITY.md` "v1.0 audit scope" section.
+
+## [0.5.0] — 2026-05-25 — OSS launch
+
+### Added — Governance + docs
+
+- **CONTRIBUTING.md** — clean-room policy (W-002), quality gates, contribution checklist for new tools / adapters / companion endpoints, single-backend rule (W-011), DCO sign-off.
+- **CODE_OF_CONDUCT.md** — Contributor Covenant v2.1.
+- **SECURITY.md** — supported-versions matrix, 90-day private disclosure window, threat model for Node MCP + companion, in-scope items for v1.0 external audit.
+- **docs/MIGRATION-FROM-NOVAMIRA.md** — feature parity matrix, coexistence flow (Phase 0 → 4), key behavioral differences, "use which" honest framing.
+- **.github/ISSUE_TEMPLATE/{bug_report,feature_request}.md** — structured intake.
+
+### Pairs with
+
+- `rolepod-wplab-companion` v0.2 (unchanged for v0.5).
+
+### Tests
+
+- 117 unit + smoke green. 46 MCP tools. `claude plugin validate ./ --strict` pass.
+
+### Not in v0.5 (deferred to v1.0)
+
+- npm publish to `@rolepod/wplab` — requires npm org claim + publish workflow.
+- wordpress.org plugin directory submission for companion — requires WP review.
+- Astro docs site (RECIPES.md remains the primary doc surface).
+- Real replay tool dispatch (currently stub).
+- External security audit.
+- Conformance test suite for 3rd-party adapters.
+
+## [0.4.0] — 2026-05-25
+
+### Added — Polish
+
+- **Replay bundle format v1.** Schema in `src/bin/replay.ts`. CLI: `rolepod-wplab replay <bundle.json>`. v0.4 stub-dispatches calls (logs only); v0.5 wires actual in-process MCP CallTool dispatch loop.
+- **Dockerfile** for ghcr.io publish target. Multi-stage (build node20 → runtime node20-alpine). Entrypoint = `rolepod-wplab serve`.
+- **GitHub Actions CI** (`.github/workflows/ci.yml`) — Node 20+22 × ubuntu+macos matrix; typecheck + build + test + lint + prettier + docker build (no push).
+- **docs/RECIPES.md** — 10 concrete end-to-end recipes (connect local/remote, scaffold block, audit multi-site, migrate plugins, hook debug, bulk Woo update, memory recall, execute-php, docker fixture).
+
+### Changed
+
+- `rolepod-wplab` CLI usage line lists all subcommands: serve | doctor | credentials | memory | replay | smoke.
+
+### Not yet implemented (deferred to v0.5)
+
+- Replay actually executes tool calls (currently stubs to logs).
+- Docs site (Astro). RECIPES.md serves as v0.4 doc surface.
+- WooCommerce optional pack (existing adapter writes cover most use cases).
+- Adapter test framework with real fixture coverage.
+
+## [0.3.0] — 2026-05-25
+
+### Added — Multi-target + cross-target composites + SEO/i18n adapters
+
+**New target kinds (W-009):**
+- `SshTarget` — node-ssh based. Supports private_key_path or password auth. wp-cli via ssh exec; fileRead/fileWrite via SFTP.
+- `DockerTarget` — dockerode based. `docker exec` per call. File ops via stdin-piped tee. Demuxes docker stream multiplex header.
+- `factory.openTarget` handles 4 kinds: local | rest | ssh | docker.
+
+**New MCP tools (8 — total 46, was 34 in v0.2):**
+- `rolepod_wp_connect_ssh { host, user, wp_path, port?, private_key_path?, password? }`
+- `rolepod_wp_connect_docker { container_name, wp_path?, docker_host?, docker_socket_path? }`
+- `rolepod_wp_audit_many { target_ids[], report_format? }` — fan out audit across N targets, consolidate.
+- `rolepod_wp_migrate_data { source_target_id, dest_target_id, scope, allow_destructive:true, confirm? }` — v0.3 supports plugin_versions only (install/upgrade dest to match source).
+- `rolepod_wp_wpml_read { target_id, scope, domain?, post_id? }` — languages / string_translations / post_translations.
+- `rolepod_wp_yoast_read { target_id, scope, post_id? }` — post_meta / settings.
+- `rolepod_wp_rankmath_read { target_id, scope, post_id? }` — post_meta / settings.
+
+**Adapters (3 new):**
+- `wpml/read` — supportedRange 4.5 — 4.7.
+- `yoast/read` — supportedRange 21.0 — 23.5.
+- `rankmath/read` — supportedRange 1.0.200 — 1.0.220.
+
+### Deps
+
+- `@types/dockerode` added to devDependencies.
+- `node-ssh` + `dockerode` (optionalDependencies from v0.0) now actually pulled.
+
+### Pairs with
+
+- `rolepod-wplab-companion` v0.2 (unchanged for v0.3).
+
+### Tests
+
+- 117 unit + smoke green (smoke asserts 46 tools).
+- claude plugin validate --strict pass.
+- Lint + prettier + typecheck clean.
+
+## [0.2.0] — 2026-05-25
+
+### Added — Companion online + Memory + Power tools
+
+**Memory (W-028):**
+- `MemoryStore` — per-site file-based storage at `~/.config/rolepod-wplab/memory/<site-slug>/` (mode 0700 dir, 0600 files). Layout: meta.json + site.md + notes.md (append-only) + conventions.md (versioned append) + runbooks/*.md.
+- `rolepod_wp_memory_recall { target_id, query?, kind? }` — substring + kind filter.
+- `rolepod_wp_memory_note { target_id, content, kind?, runbook_name?, tags? }` — append note / version convention / replace runbook.
+- `rolepod_wp_memory_list { target_id }` — metadata-only file listing.
+- CLI: `rolepod-wplab memory show | list | clear | export`.
+
+**Companion bridge + power tools (W-003R, W-004R):**
+- `src/companion/Bridge.ts` — handshake + session token mgmt + AST pre-screen + auto-refresh on 401.
+- `src/safety/AstScreen.ts` — token-blocklist screen (defence in depth with companion v0.1+ PHP-side screen). Rejects eval/assert/system/exec/shell_exec/proc_open/popen/pcntl_*/dl/backtick/dynamic-include.
+- `rolepod_wp_execute_php { target_id, payload, timeout_ms?, confirm:true }` — requires `ROLEPOD_WPLAB_PROFILE=power`.
+- `rolepod_wp_introspect { target_id, scope, include_values? }`.
+- `rolepod_wp_hook_state { target_id, hook, kind? }` — specialized wrapper over introspect(scope=hooks).
+
+**Adapter writes + Bricks (W-023 extended):**
+- `elementor/write.updatePageData` — auto-backup `_elementor_data` before overwrite.
+- `woocommerce/write.updateProduct` + `bulkUpdatePrices` (via /wc/v3/products/batch).
+- `acf/write.setPostMeta` — ACF Pro REST first, wp-cli fallback.
+- `bricks/read` adapter — listPages + getPage (parses `_bricks_page_content_2`). supportedRange 1.8 — 1.10.
+- 4 new MCP tools: `wp_elementor_write`, `wp_woo_write`, `wp_acf_write`, `wp_bricks_read`. All writes enforce production guard.
+
+**Composites (5 total):**
+- `rolepod_wp_scaffold_block` — generates block.json + index.js + render.php (or save) + style.css.
+- `rolepod_wp_scaffold_plugin` — main PHP + readme + uninstall + optional rest_endpoint/admin_page/cli_command stubs.
+- `rolepod_wp_scaffold_theme` — block-theme skeleton (style.css + theme.json + functions.php + templates).
+- `rolepod_wp_audit_security` — chains wp-cli checks + writes audit-report.md/.json.
+- `rolepod_wp_migrate_dryrun` — diffs two targets across plugin_versions / options / users / posts.
+
+**Shipped skills (6 new — total 10):**
+- `wp-execute-php` (companion-gated, power profile required)
+- `wp-introspect` (companion-gated)
+- `wp-edit-elementor` (adapter)
+- `wp-audit-woo` (adapter composite)
+- `wp-scaffold-theme`
+- `wp-migrate-dryrun`
+
+**MCP tools: 34 total** (was 19 in v0.1). All registered + tools/list smoke updated to assert exact list.
+
+### Changed
+
+- `Target` interface: `TargetKind` unchanged but bridge layer now exercises `Target.rest()` for companion communication on all target kinds (RestTarget today; v0.3 SSH/Docker via companion remote install).
+- `loadProfile()` recognizes `power` profile (was placeholder in v0.1 schema).
+
+### Pairs with
+
+- `rolepod-wplab-companion` v0.2 — adds `/wp-cli` (bundled wp-cli proxy), `/fs-read`, `/fs-write`, `/php-session`, `/request-observer`. `execute-php` default-enabled.
+
+### Tests
+
+- 117 unit + smoke tests green (memory 17 + AstScreen 13 added).
+- `claude plugin validate ./ --strict` passes.
+- Lint + prettier + typecheck all clean.
+
+## [0.1.0] — 2026-05-25
+
+### Added — PoC complete (Path C foundation)
+
+**Runtime layer:**
+- `RestTarget` (W-027) — remote WordPress via HTTPS REST + optional companion. No host wp-cli, no SSH needed. Closes shared-hosting gap.
+- `restClient` — Basic-Auth App Password, content-type sniffing, `?rest_route=` fallback for permalink-disabled WP, AbortController timeout, redacts auth from error context.
+- `Target` interface gains `companion: CompanionStatus | null` field. `executePhp` / `introspect` are optional methods (companion-gated).
+- Companion handshake at every target-open. 200 + power profile + non-prod → power tools available. Else → power tools unregistered.
+
+**Credentials (W-018, W-027):**
+- Vault interface: `add` / `get` / `list` / `remove` / `touch`.
+- `KeychainVault` — macOS Keychain via `security` binary + sidecar metadata JSON.
+- `FileVault` — JSON at mode 0600 (Linux + portable fallback).
+- `makeVault()` — auto-detects platform; `ROLEPOD_WPLAB_VAULT=file|keychain` override.
+- `canonicalizeSite()` — lowercase hostname extraction.
+- `Credential` type carries `appPassword` (raw secret, never serialized to MCP responses or audit log).
+- `prompt.ts`: `ask` / `askSecret` (raw-mode no-echo) / `confirm` — no extra deps.
+- CLI subcommand `rolepod-wplab credentials <add|list|show|remove|test> [site]`.
+
+**MCP tools — 19 total (was 5 in v0.0):**
+
+Connectivity + lifecycle:
+- `rolepod_wp_connect_local { path }`
+- `rolepod_wp_connect_rest { url, credential_ref?, require_companion? }` (NEW)
+- `rolepod_wp_disconnect { target_id }` (NEW)
+
+Atomic surface:
+- `rolepod_wp_cli_run { target_id, args, allow_destructive?, timeout_ms? }`
+- `rolepod_wp_health_check { target_id }`
+- `rolepod_wp_file_read { target_id, path }`
+- `rolepod_wp_file_write { target_id, path, content, mode?, backup?, confirm_unsafe_path? }`
+- `rolepod_wp_post_get { target_id, id, context?, type? }` (NEW)
+- `rolepod_wp_post_list { target_id, type?, per_page?, page?, search?, status?, ... }` (NEW)
+- `rolepod_wp_post_create { target_id, title, content, status?, ... }` (NEW)
+- `rolepod_wp_post_update { target_id, id, title?, content?, status?, ... }` (NEW)
+- `rolepod_wp_option_get { target_id, name }` (NEW)
+- `rolepod_wp_option_set { target_id, name, value, confirm? }` (NEW)
+- `rolepod_wp_user_list { target_id, per_page?, page?, search?, role? }` (NEW)
+- `rolepod_wp_db_query { target_id, sql, allow_write?, confirm? }` (NEW)
+- `rolepod_wp_rest_request { target_id, method, path, query?, body?, headers? }` (NEW)
+
+Adapter-backed (read-only v0.1, W-023):
+- `rolepod_wp_elementor_read { target_id, page_id?, type?, per_page? }` (NEW)
+- `rolepod_wp_woo_read { target_id, scope, group?, per_page?, search?, status? }` (NEW)
+- `rolepod_wp_acf_read { target_id, scope, group_key?, post_id? }` (NEW)
+
+**Adapters (src/adapters/):**
+- `_contract.ts` — `Adapter<TRead, TWrite>` interface + `AdapterUnavailableError`.
+- `elementor/read` — listPages (REST), getPage (wp-cli post meta; RestTarget needs companion v0.2). supportedRange: 3.18 — 3.22.
+- `woocommerce/read` — products, orders, settings_groups, settings_in_group, shipping_zones, payment_gateways via `/wc/v3` REST. supportedRange: 8.0 — 9.4.
+- `acf/read` — fieldGroups, fieldsInGroup, postMeta via wp-cli + ACF Pro REST fallback. supportedRange: 6.0 — 6.3.
+
+**Safety:**
+- `DbGuard` (W-007) — SELECT/SHOW/DESCRIBE/DESC/EXPLAIN allow-list. Strips leading comments + handles `WITH ... SELECT` (CTE). `DbWriteBlockedError` on violation.
+- All write tools enforce `ProdGuard` (W-008) unless `confirm: true`.
+
+**Plugin layout (Claude Code, verified against https://code.claude.com/docs/en/plugins-reference + /skills):**
+- `.claude-plugin/plugin.json` — metadata only (NO inline `mcpServers`; that lives in `.mcp.json`).
+- `.mcp.json` at plugin root — declares MCP server pointing at `${CLAUDE_PLUGIN_ROOT}/dist/bin/rolepod-wplab.js`.
+- `skills/wp-health-check/SKILL.md`
+- `skills/wp-scaffold-block/SKILL.md`
+- `skills/wp-scaffold-plugin/SKILL.md`
+- `skills/wp-audit-security/SKILL.md`
+- `claude plugin validate ./ --strict` passes.
+
+Cursor + Codex + Gemini manifests NOT shipped this release — schemas not yet verified per SCHEMA-BOUND-file policy. Deferred to v0.5.
+
+**Tests — 87 green:**
+- `tests/unit/server.test.ts` (18) — server boot + AllowList + ProdGuard + FsScope
+- `tests/unit/TargetRegistry.test.ts` (8) — lifecycle + idle close + collision
+- `tests/unit/profile-load.test.ts` (6) — env / file / malformed
+- `tests/unit/stripPhpNoise.test.ts` (9)
+- `tests/unit/credentials.test.ts` (16) — canonicalize + FileVault round-trip + permissions + corruption
+- `tests/unit/restClient.test.ts` (12) — https-only + auth header + URL form fallback + timeout + redaction + query encoding
+- `tests/unit/DbGuard.test.ts` (15) — SELECT/SHOW/DESC/EXPLAIN allow + CTE + INSERT/UPDATE/DELETE/DROP/TRUNCATE/ALTER block + comments
+- `tests/smoke/mcp-handshake.test.ts` (3) — spawn dist + JSON-RPC + tools/list asserts 19 tools
+
+### Changed
+
+- `Target.kind` type now includes `'rest'`.
+- `runtime/wpCli.ts` adds `stripPhpNoise()` filter for wp-cli 2.12 on PHP 8.4 deprecation noise.
+- `wp_health_check` DB probe switched from `wp db check` (needs host mysqlcheck) to `wp option get siteurl` (PHP mysqli only).
+
+### Pairs with
+
+- `rolepod-wplab-companion` v0.1 — optional WP plugin providing `/wp-json/wplab/v1/{handshake,introspect,execute-php}` endpoints. execute-php DISABLED by default in v0.1.
+
+## [0.0.0] — 2026-05-25
+
+### Added — personal-use scaffold
+
+- Repo plumbing: TypeScript + tsup + vitest + oxlint + prettier.
+- MCP server skeleton (stdio).
+- `LocalTarget` runtime (wp-cli + REST stub + scoped fs).
+- 5 atomic tools.
+- Safety primitives: AllowList + FsScope + ProdGuard.
+- 3-profile loader (`strict` / `personal` / `power` slot).
+- Docker WP fixture (`tests/fixtures/`) for local dogfood.
+- 44 unit + smoke tests.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 nuttaruj
+
+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.

package/README.md

@@ -0,0 +1,101 @@
+# rolepod-wplab
+
+**Status:** v0.1.0 — PoC complete (Path C foundation). Not yet published to npm; use locally via `npm link` or `claude --plugin-dir`.
+
+Novamira-class WordPress operations toolkit for AI coding agents — default-safe wp-cli + REST + scoped filesystem, opt-in companion plugin ([`rolepod-wplab-companion`](https://github.com/nuttaruj/rolepod-wplab-companion)) for `execute-php` + runtime introspection. MIT, sibling of [rolepod-uiproof](https://github.com/nuttaruj/rolepod-uiproof) in the rolepod ecosystem.
+
+## Two layers
+
+| Layer | Install | Capability |
+|---|---|---|
+| **Default** | `claude --plugin-dir ./rolepod-wplab` (or marketplace once v0.5) | wp-cli + REST + scoped fs + 19 MCP tools (3 adapters for Elementor / WooCommerce / ACF read) |
+| **Power** (opt-in) | + install [`rolepod-wplab-companion`](https://github.com/nuttaruj/rolepod-wplab-companion) WP plugin + `ROLEPOD_WPLAB_PROFILE=power` | adds `execute-php`, `introspect`, adapter writes (v0.2+) |
+
+## Quick start (local dev)
+
+```bash
+git clone https://github.com/nuttaruj/rolepod-wplab.git
+cd rolepod-wplab
+npm install
+npm run build
+
+# Test with Claude Code:
+claude --plugin-dir ./
+
+# Or register globally:
+npm link
+claude mcp add wplab -- rolepod-wplab
+
+# Verify:
+rolepod-wplab doctor
+```
+
+## Connecting to a WP target
+
+**Local install** (filesystem path):
+```
+> "เชื่อม WP ที่ /Users/me/Sites/my-wp"
+Lead → rolepod_wp_connect_local { path: "/Users/me/Sites/my-wp" }
+```
+
+**Remote site** (REST + App Password):
+```bash
+# 1. WP admin → Users → Profile → Application Passwords → name "rolepod-wplab" → copy
+# 2. Store locally (never echoed to chat):
+rolepod-wplab credentials add walnutztudio.com
+# Username: admin
+# Application Password: ****
+# ✓ stored in keychain
+```
+```
+> "เชื่อม walnutztudio.com"
+Lead → rolepod_wp_connect_rest { url: "https://walnutztudio.com" }
+```
+
+## 19 MCP tools available
+
+**Connectivity:** `connect_local`, `connect_rest`, `disconnect`, `health_check`
+**wp-cli passthrough:** `cli_run` (allow-listed)
+**REST CRUD:** `post_{get,list,create,update}`, `user_list`, `rest_request`
+**Options:** `option_{get,set}`
+**Database:** `db_query` (SELECT-only by default)
+**Filesystem:** `file_{read,write}` (scoped to `wp-content/{themes,plugins,uploads}` + `wp-config.php`)
+**Adapters (read):** `elementor_read`, `woo_read`, `acf_read`
+
+All prefixed `rolepod_wp_*`. Schemas in `src/schema/tools.ts`.
+
+## Safety defaults
+
+- **Allow-list** wp-cli (W-005) — `db reset`, `db drop`, `core multisite-convert` never run from MCP.
+- **SELECT-only** DB queries (W-007) by default; `allow_write: true` + `confirm: true` on prod.
+- **Scoped filesystem writes** (W-006) — `wp-content/{themes,plugins,uploads}` + `wp-config.php` only.
+- **Production guard** (W-008) — siteurl glob match against `ROLEPOD_WPLAB_PROD_HOSTS`; all write tools require `confirm: true` on match.
+- **HTTPS-only** RestTarget (W-017) — App Password never travels plaintext.
+- **Credentials in OS keychain** (W-018) — never in chat history, never in audit log.
+
+Power tools (with companion + `power` profile) add:
+- **AST screen** for execute-php payloads (Node-side + companion-side, defence in depth).
+- **Production-block unconditional** for execute-php — no override exists.
+- **Append-only audit log** for every execute-php call (success + rejection).
+
+## Skills (4 in v0.1)
+
+- `/rolepod-wplab:wp-health-check` — diagnostic snapshot
+- `/rolepod-wplab:wp-scaffold-block` — Gutenberg block scaffold (composite lands v0.2)
+- `/rolepod-wplab:wp-scaffold-plugin` — plugin skeleton (composite lands v0.2)
+- `/rolepod-wplab:wp-audit-security` — CVE + outdated + perms audit (composite lands v0.2)
+
+v0.2 adds: `/wp-execute-php`, `/wp-introspect`, `/wp-edit-elementor`, `/wp-audit-woo`, `/wp-scaffold-theme`, `/wp-migrate-dryrun`.
+
+## Sibling repos
+
+- [`rolepod-wplab-companion`](https://github.com/nuttaruj/rolepod-wplab-companion) — optional WP plugin for runtime PHP context.
+- [`rolepod-uiproof`](https://github.com/nuttaruj/rolepod-uiproof) — UI / mobile automation sibling.
+
+## Design
+
+Path C stance (W-026): same capability ceiling as Novamira, default-safe posture, opt-in companion for runtime PHP context. Differentiation matrix + decision log in the [internal design brief](./brief/) (gitignored, maintainer-only — reconstructable from conversation context if lost).
+
+## License
+
+MIT — see [LICENSE](./LICENSE). Clean-room from [Novamira](https://github.com/use-novamira/novamira) (AGPL-3.0); no Novamira code was read or copied.

package/dist/bin/rolepod-wplab.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node