@wix/agent-skills 1.15.0 → 1.16.0

package/skills/wix-replatform/resources/rp-execute-setup/SKILL.md

@@ -0,0 +1,316 @@
+---
+name: rp-execute-setup
+description: >-
+  Verifies and provisions Wix-side setup required before import. Use after codegen when
+  machine-readable setup artifacts must be validated or executed against the target site.
+---
+
+# rp-execute-setup
+
+Verify that required Wix-side setup exists and is ready for import.
+
+## Purpose
+
+This skill validates the prerequisites discovered by `rp-setup-discovery`. It can also drive the setup work when the environment and permissions allow it.
+
+## Required inputs
+
+- `migrations/<project>/setup/setup-plan.json`
+- `migrations/<project>/setup/setup-requirements.json`
+- `migrations/<project>/execution/execution-manifest.json`
+- `migrations/<project>/config/wix.env` or equivalent environment values
+- access to the target Wix environment or to exported evidence from that environment
+
+Prefer the machine-readable setup artifacts above. Markdown setup summaries are secondary
+renderings for humans, not the primary execution contract.
+
+## Config
+
+Prefer project-local config over ad hoc shell state. `config/wix.env` should exist before
+setup verification/provisioning and contain:
+
+```bash
+WIX_SITE_STRATEGY=
+WIX_SITE_ID=
+WIX_AUTH_TOKEN=
+```
+
+`WIX_SITE_STRATEGY` is always required. `WIX_SITE_ID` is required before setup
+verification/provisioning begins. If the strategy is `new` and no site has been created
+yet, halt to needs-user and route back to the site-creation step rather than asking for an
+existing site ID. `WIX_AUTH_TOKEN` is the canonical Wix credential key for this project
+flow; for CLI-scaffolded headless sites it holds the site write credential (a CLI token
+sent as a Bearer token). **Never print secret values.** Mint the token without printing it
+to the transcript by running `scripts/mint-token.sh` from the migration project root:
+
+```bash
+bash migrations/<project>/scripts/mint-token.sh
+```
+
+The canonical copy lives at
+`skills/replatform/resources/rp-execute-setup/scripts/mint-token.sh`.
+`rp-import-codegen` copies it into `migrations/<project>/scripts/` at scaffolding time —
+do not write it from scratch. The script reads `WIX_SITE_ID` from `config/wix.env`, calls
+`npx @wix/cli@latest token --site "$WIX_SITE_ID"`, captures stdout (token shape:
+`OauthNG.JWS.<base64>.<base64>.<sig>`), writes it directly into `config/wix.env` as
+`WIX_AUTH_TOKEN`, and prints only a char-count confirmation. Do NOT run the token command
+raw in a Bash tool call — it prints the credential to transcript.
+
+If `WIX_SITE_ID` is missing for a RePlatform `new site` + `headless` flow, the recovery
+path is the **Wix CLI headless scaffold** step defined in `replatform` → "Headless site
+creation" (`npm create @wix/new@latest headless`). The account-level Projects API is
+deprecated for this workflow. **Note:** the scaffold does not install Wix Stores — this
+skill (setup) is where Wix Stores and other required apps get installed (via the
+`wix-manage` skill / app-install path), then verified, before import.
+
+Treat `migrations/<project>/config/*.env` as secret-bearing once they may contain real
+values. Do not verify them with whole-file reads that echo contents into tool output.
+Only check existence plus `present` / `blank` / `missing` status for required keys.
+
+## Workflow
+
+1. Resolve the active project.
+2. Read the machine-readable setup artifacts.
+3. Verify each required app, collection, schema, field, and permission through the shared
+   setup runtime contract.
+   If setup requirements came from domain knowledge, preserve the originating `targetRef`
+   in verification output so later execution warnings can be traced back to the selected
+   entity guidance.
+4. Record pass, fail, or blocked status for each item.
+5. If execution is allowed, perform missing setup steps through the shared setup runtime
+   and re-verify.
+6. Save the verification results and setup execution artifacts.
+
+## Execute the setup artifacts — do not re-derive setup from prose
+
+Setup execution should follow the approved machine artifacts and the shared setup runtime.
+It should not rebuild setup decisions from markdown or ad hoc reasoning when
+`setup/setup-plan.json`, `setup/setup-requirements.json`, and `execution/execution-manifest.json`
+already exist.
+
+This skill owns execution of those artifacts. It does not own redefining the setup plan
+or creating a separate setup approval checkpoint.
+
+Dry-run setup uses the same setup plan and setup executor as live setup. When `DRY_RUN`
+is enabled by config or `--dry-run`, every setup step must first be reduced to a
+structured intent describing the REST request, SDK operation, MCP tool call, or CLI
+command that live setup would use. The shared setup runtime then captures that intent,
+marks the step `planned_dry_run`, and must not invoke Wix MCP tools, Wix CLI commands,
+SDK calls, or fetch calls that access or mutate Wix account/site state.
+
+Do not override `DRY_RUN=true` with `--no-dry-run` for setup verification or provisioning
+unless the user has explicitly approved leaving dry-run for setup. Prefer to avoid that
+override entirely when a dry-run or plan/report can answer the question. The one allowed
+live action while a project otherwise remains in dry-run mode is the separate new-site
+creation step handled upstream by `replatform`; this skill must not treat that exception
+as permission to run live setup writes or live setup verification probes.
+
+Dry-run setup must not update `setup/setup-verification.json` in a way that claims a Wix
+capability, app installation, collection, or site exists. Write a separate dry-run setup
+report or clearly dry-run-scoped observations instead.
+
+## Provisioning — exhaust programmatic options before declaring anything "manual"
+
+Default to provisioning via API. Do **not** label a requirement "manual" or "owner
+action" until you have confirmed no API can do it.
+
+The preferred contract is a **shared setup runtime** owned by `rp-target-wix`, executed
+against the machine setup artifacts produced upstream. This skill may use available Wix
+API/MCP surfaces as the transport beneath that runtime, but the contract at the
+RePlatform level is:
+
+- setup execution consumes machine setup artifacts
+- setup execution follows shared runtime behavior
+- setup provisioning is not re-planned live by the agent
+
+The approval gate is unchanged: no setup write before the user accepts the execution
+plan.
+
+If a helpful Wix tool surface is available in the runtime, it may be used beneath the
+shared setup runtime for verification or transport. If no such surface is available, do
+not treat that alone as a blocker; continue with the shared setup/runtime contract and
+verified `rp-target-wix` behavior, marking unverified items where needed.
+
+Only proceed in a docs-only/read-only posture when the MCP is genuinely unavailable and
+the step can still produce useful non-destructive output.
+
+Concrete mechanisms:
+
+- **Mute site notifications FIRST (spec 0012).** When the setup artifacts carry the
+  `mute-site-notifications` requirement (always for `WIX_SITE_STRATEGY=new`; opt-in for
+  existing sites), execute it **before every other setup write** — immediately after the
+  target site is available and `WIX_AUTH_TOKEN` is minted, and before app installs,
+  collection creation, or any other provisioning — so setup writes themselves cannot
+  fire notifications. Use the `muteSiteNotifications` primitive from
+  `rp-target-wix/lib/wix-writers.js` (VERIFIED 2026-08-04) with a project-identifying
+  reason (`RePlatform migration — <project>`); verify via `getSiteMuteState` →
+  `muted: true` (verification method `status-read`; an idempotent re-mute is only a
+  documented fallback, method `idempotent-recall`). Record the result in
+  `setup/setup-verification.json` on the requirement at call time — status
+  (`pass`/`fail`/`blocked`), timestamp, and verification method — like any other
+  verified item; downstream reports read this recorded state, never infer it. **AUTH
+  TRAP:** the endpoints accept user tokens only — the CLI-minted `OauthNG` site token
+  works; an account API key gets an empty-body 403. **A failed mute is a blocker, not a
+  warning:** the run halts to needs-user and never proceeds to import writes — no
+  degraded mode, no continue-anyway. Never call `unmuteSiteNotifications` from this
+  skill — unmute is an explicit owner request handled at the orchestrator level.
+  Record the provision outcome through the standard `rp-telemetry` recorder like any
+  other notable boundary (an `error` event with `error_code` on failure; the
+  existing-site opt-in surfaces via the approval gate's `user_decision` event) — no new
+  telemetry surface.
+- **Installing / enabling Wix apps (Blog, Members, etc.) IS automatable.** Use the
+  App Installation API:
+  1. Pre-check with `POST /apps-installer-service/v1/app-instance/is-permitted-to-install`
+     (read-only) to see whether the identity may install the app.
+  2. If permitted, install with `POST /apps-installer-service/v1/app-instance/install`.
+     Body (all fields required — confirmed by live 400s): `{ appInstance: { appDefId,
+     enabled: true }, tenant: { tenantType: "SITE", id: <siteId> }, installType:
+     "INSTALL_TYPE_SITE", appsInstallOptions: {} }`. (The `is-permitted-to-install`
+     pre-check uses a *different*, oneof-based body and is informational only — if its
+     validation fights you, skip it and rely on `/install`.)
+  3. List current state with `GET /apps-installer-service/v1/app-instances`.
+  - **Ground `appDefId` from the official "Apps Created by Wix" table**
+    (`/docs/api-reference/articles/work-with-wix-apis/platform/about-apps-created-by-wix`),
+    NOT from a docs *example* — e.g. the install-app example uses
+    `1380b703-…`, which is **Wix eCommerce**, not Blog. Installing the wrong app on a
+    live site is a real hazard; verify the ID maps to the app you intend.
+  - **After installing Wix Stores, verify the catalog is V3 — before any Stores write.**
+    Installing Stores does **not** guarantee Catalog V3: on a site scaffolded from the
+    `blank` headless template, the install comes up **`V1_CATALOG`**, which the V3 Stores
+    primitives cannot write to (verified the hard way on a live migration, 2026-07-30).
+    Catalog version is fixed at provisioning — there is no in-place V1 → V3 switch. Check it
+    with the read-only Catalog Versioning API:
+
+    ```bash
+    curl -s -H "Authorization: Bearer $WIX_AUTH_TOKEN" -H "wix-site-id: $WIX_SITE_ID" \
+      https://www.wixapis.com/stores/v3/provision/version
+    ```
+
+    `catalogVersion` is `V3_CATALOG` (proceed), `STORES_NOT_INSTALLED` (install, re-check),
+    or `V1_CATALOG` — record it as a **blocker** in `setup/setup-verification.json`, write
+    nothing to Stores, and halt to needs-user. The prevention lives upstream of this skill
+    (`replatform` → "Headless site creation": scaffold with `--site-template commerce`); the
+    recovery is a user-approved replacement site, **never** a silently created one, and
+    never a throwaway probe site.
+- **Wix Data / CMS collections (the `WDE0110: Wix Code not enabled` case).** Enable Wix
+  Data by **installing the Wix Data app `appDefId e593b0bd-b783-45b8-97c2-873d42aacaf4`**
+  via the App Installation API (same `/install` body shape as any other app; it also
+  auto-installs a dependency app `1a711f05-2040-47df-a9f0-4f9cddb4c3c6`). Once installed,
+  plain REST `POST /wix-data/v2/collections` creates **NATIVE** collections with no
+  `WDE0110` — no code editor toggle, no custom app needed. **Verified live 2026-06-10**
+  on a fresh free site (install → 200; collection create → 200 `collectionType: NATIVE`).
+  - This is the preferred path. The older data-collections-extension app (authoring a
+    custom app that declares collections) is now a **fallback** — only needed if
+    you must declare collection schemas at install time, and it still can't express
+    `REFERENCE` fields (add those after install via `create-field`).
+  - Note: the standalone "Wix CMS" app (`appDefId 675bbcef-…`) is **not** installable
+    (`is-permitted-to-install` → `false`) — do **not** use it; use `e593b0bd-…`.
+- **Optional import crosswalk CMS mirror.** Native Wix entities use local crosswalk state
+  under `migrations/<project>/state/crosswalk/` for idempotency. Provision a native
+  **`ImportCrosswalk`** collection only when the approved setup artifacts explicitly
+  request a CMS mirror for existing-site seeding or site-local reference. After enabling
+  Wix Data, create it with `POST /wix-data/v2/collections` and fields such as
+  `entityType` (TEXT), `sourceId` (TEXT), `sourceStableKey` (TEXT), `targetId` (TEXT),
+  `targetType` (TEXT), and `updatedAt` (DATETIME/TEXT). Do not provision this collection
+  as the default native-entity idempotency mechanism. If upstream artifacts still call the
+  optional mirror `MigrationRefs`, normalize them here rather than creating both
+  collections.
+- **Genuinely manual (no API exists):** upgrading the storage plan, generating
+  external-system credentials (e.g. a WordPress Application Password), and
+  account-level billing. These are the only categories that may be reported as manual —
+  and only after confirming no API covers them.
+
+## Artifact to create or update
+
+- `migrations/<project>/setup/setup-verification.json`
+- `migrations/<project>/setup/review/setup-verification.md`
+- audit/report artifacts emitted by the shared setup runtime
+- dry-run request captures in `migrations/<project>/state/attempts/wix-request-captures.ndjson`
+  when setup is run with dry-run enabled
+
+Stores live setup checks that require a probe record must use the shared rp-target-wix
+verification CLI, not ad hoc snippets. For subscription support, run:
+
+```bash
+node skills/replatform/resources/rp-target-wix/scripts/verify-stores.js stores subscription-create \
+  --artifact migrations/<project>/setup/stores-subscription-verification.json \
+  --proposal-artifact migrations/<project>/setup/contract-ledger-proposal.json
+```
+
+Keep the JSON verification artifact and contract-ledger proposal alongside setup
+verification. The proposal is not itself shared product knowledge; the orchestrator must
+promote accepted proposal data into `rp-target-wix/domains/**/entities/*.json` in the same
+session or record a deferral reason. If cleanup fails, do not mark the probe as clean;
+preserve the warning and run the emitted `stores delete-probe` recovery command after
+permissions or target state are fixed.
+
+## Verification output format
+
+For each requirement capture:
+
+- requirement name
+- expected state
+- observed state
+- status: passed, failed, blocked
+- remediation needed
+
+The machine-readable verification artifact should also preserve:
+
+- stable requirement ID
+- checkpoint/provisioning step ID when applicable
+- verification evidence reference
+- automation mode: `automatable | manual | blocked | unverified`
+
+## Optional media reachability verification
+
+When the migration includes media import by source URL, check whether discovered media
+URLs are publicly reachable by Wix. If the source URL is `localhost`, `127.0.0.1`, or a
+private-only host, mark **media import** as `blocked` or `deferred`, but do not block
+unrelated non-media entities. This is optional setup and, as far as we know today, affects
+only Wix Media import.
+
+Record the user's chosen path in `setup/setup-verification.json` and render it into the
+review markdown:
+
+- **Tunnel media URLs:** ask the user to expose the source through a public HTTPS tunnel,
+  then use that URL for `WP_BASE_URL` / `SOURCE_URL` or rewrite media URLs to that base.
+- **Skip/defer media:** proceed only if the execution plan clearly says media and any
+  media-dependent references (hero images, galleries, downloads) will be skipped or
+  deferred.
+
+Ngrok quick setup for macOS:
+
+```bash
+brew install ngrok
+ngrok config add-authtoken "<YOUR_AUTHTOKEN>"
+ngrok http 8090
+export WP_BASE_URL=https://<id>.ngrok-free.app
+```
+
+## Runtime policy
+
+Split this skill's work by side effect:
+
+- **Verification is read-only** — checking what's installed, what's missing, and what's
+  genuinely manual. It runs **before** the execution-plan acceptance gate and feeds the
+  plan.
+- **Provisioning writes** — installing apps, enabling Wix Data (via the data-collections
+  enabler), creating collections, adding fields — happen **only after** the user accepts
+  the execution plan. **No site write before acceptance.** Once accepted, the "Migrate"
+  consent covers the individual writes, so don't re-prompt per app/collection. Halt to
+  needs-user only for genuinely manual items (storage-plan upgrade) or a
+  missing/invalid credential.
+
+The execution behavior itself should come from the shared setup runtime and approved
+setup artifacts, not from improvised per-run logic in this skill.
+
+## Guardrails
+
+- Never report setup as complete without evidence.
+- Prefer machine-readable setup verification artifacts over prose-only reporting.
+- Before marking an item blocked or manual, confirm no API can perform it (see
+  Provisioning above). Reserve "manual" for storage/billing/external-credential steps.
+- If credentials or permissions are genuinely missing, mark the item blocked and state
+  the exact API that was refused and why.
+- Do not start import execution from this skill.
+- Do not reinterpret setup requirements from markdown when machine artifacts exist.

package/skills/wix-replatform/resources/rp-execute-setup/scripts/mint-token.sh

@@ -0,0 +1,64 @@
+#!/usr/bin/env bash
+# Mints a fresh Wix CLI token for a migration project's site and writes it
+# directly into config/wix.env as WIX_AUTH_TOKEN — never printing the value.
+#
+# Usage (from the migration project root):
+#   bash scripts/mint-token.sh
+#
+# Reads WIX_SITE_ID from config/wix.env.
+# Requires: npx @wix/cli@latest (logged in — check: npx @wix/cli@latest whoami)
+#
+# This is the canonical copy. rp-import-codegen copies it into
+# migrations/<project>/scripts/mint-token.sh during project scaffolding.
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(dirname "$SCRIPT_DIR")"
+CONFIG_FILE="$PROJECT_ROOT/config/wix.env"
+
+if [[ ! -f "$CONFIG_FILE" ]]; then
+  echo "Error: config file not found: $CONFIG_FILE" >&2
+  exit 1
+fi
+
+WIX_SITE_ID=$(grep '^WIX_SITE_ID=' "$CONFIG_FILE" | cut -d'=' -f2- | tr -d '[:space:]')
+
+if [[ -z "$WIX_SITE_ID" ]]; then
+  echo "Error: WIX_SITE_ID is blank in $CONFIG_FILE" >&2
+  exit 1
+fi
+
+echo "Minting token for site $WIX_SITE_ID ..." >&2
+
+# Capture token only on stdout; suppress CLI spinner/progress on stderr
+TOKEN=$(npx @wix/cli@latest token --site "$WIX_SITE_ID" 2>/dev/null | tr -d '[:space:]')
+
+if [[ -z "$TOKEN" ]]; then
+  echo "Error: token command returned empty output" >&2
+  exit 1
+fi
+
+# Write into config (replace existing line, or append).
+# Not `sed -i`: BSD/macOS sed requires a backup-suffix argument for -i, so the
+# portable-looking GNU form silently consumes the expression as the suffix.
+# The token is passed through the environment, never as an awk -v value or on a
+# command line, so no escape processing can corrupt it and it stays out of `ps`.
+if grep -q '^WIX_AUTH_TOKEN=' "$CONFIG_FILE"; then
+  TMP_FILE="$(mktemp "${TMPDIR:-/tmp}/wix.env.XXXXXX")"
+  trap 'rm -f "$TMP_FILE"' EXIT
+  RP_NEW_TOKEN="$TOKEN" awk '
+    /^WIX_AUTH_TOKEN=/ { print "WIX_AUTH_TOKEN=" ENVIRON["RP_NEW_TOKEN"]; next }
+    { print }
+  ' "$CONFIG_FILE" > "$TMP_FILE"
+  # Copy contents rather than mv, so the config file keeps its own permissions.
+  cat "$TMP_FILE" > "$CONFIG_FILE"
+  rm -f "$TMP_FILE"
+else
+  printf '\nWIX_AUTH_TOKEN=%s\n' "$TOKEN" >> "$CONFIG_FILE"
+fi
+
+TOKEN_LEN=${#TOKEN}
+unset TOKEN
+
+echo "✓ WIX_AUTH_TOKEN written to config/wix.env ($TOKEN_LEN chars)" >&2