/setup-embedded-app-verify

name: setup-embedded-app-verify
description: One-time setup for the Shopify embedded-app verify loop in a project. Use when the user asks to set up / configure the verify loop, or when the run-embedded-app-verify skill finds no project config.

Set up the embedded-app verify loop

Goal: a CDP-enabled, Shopify-authenticated browser plus a project config file.

1. Show the resolved developer config

The plugin config is substituted into this skill at load time:

• browser: `${user_config.browser}`
• mode: `${user_config.mode}`
• cdp_port: `${user_config.cdp_port}`

A blank value (or a literal dollar-brace placeholder) means the default applies: chrome / profile / 9222. Tell the user the resolved values and that they can be changed anytime via `/plugin` → shopify-embedded-app-verify → configure (changes reach skills after `/reload-plugins` or a session restart). Do NOT read `CLAUDE_PLUGIN_OPTION_*` env vars — they are only set for plugin subprocesses such as hooks, never for Bash commands you run.

2. Ensure the browser

Run:

node ${CLAUDE_PLUGIN_ROOT}/scripts/ensure-browser.mjs --browser "${user_config.browser}" --mode "${user_config.mode}" --port "${user_config.cdp_port}" --url "https://admin.shopify.com"

Note the `BROWSER_STATE:` line in the output — `launched-at-url`, `launched`, or `reused` — step 3 branches on it.

• Exit 0 → continue.
• `CDP_BLOCKED_DEFAULT_PROFILE` → explain: this browser refuses CDP on its

default profile (Chrome/Edge 136+). The user must switch the plugin's mode option to "profile" (dedicated automation profile, one-time login). Stop.

• `BROWSER_MISMATCH` → the CDP port is already served by a browser that is

not the configured one (and not one this plugin launched). Show the message verbatim — the user must quit that browser or change the plugin's browser/cdp_port option. Stop. (A stale automation browser from an earlier run is handled automatically — the script quits it and relaunches.)

• Other non-zero → show the message verbatim; stop.

3. Open the verify window and check Shopify authentication

Never open tabs in the developer's own windows.

**Preflight said `BROWSER_STATE: launched-at-url`** (profile mode): the browser opened directly at `https://admin.shopify.com` — its only tab IS the verify window. `browser_tabs` (action: list), select that tab, grab its targetId with `browser_run_code_unsafe`, and continue to the auth check below:

async (page) => {
  const session = await page.context().newCDPSession(page);
  const { targetInfo } = await session.send("Target.getTargetInfo");
  await session.detach();
  return targetInfo.targetId;
}

**Preflight said `BROWSER_STATE: launched` or `reused`**: the browser's tabs belong to the developer (an attach-mode relaunch restores their session — those tabs are NOT yours, whatever they show, even an admin dashboard). `browser_tabs` (action: list), then:

**Case A — the list shows only blank tabs** (`about:blank` / `chrome://new-tab-page` — a browser nobody is using): reuse that startup window instead of opening a second one. Select it, grab its targetId with `browser_run_code_unsafe`:

async (page) => {
  const session = await page.context().newCDPSession(page);
  const { targetInfo } = await session.send("Target.getTargetInfo");
  await session.detach();
  return targetInfo.targetId;
}

then `browser_navigate` it to `https://admin.shopify.com`.

**Case B — any non-blank tabs exist** (attach mode / browser already in use): open a dedicated verify window with `browser_run_code_unsafe` (the code is invoked with the current page as its single argument):

async (page) => {
  const session = await page.context().newCDPSession(page);
  const { targetId } = await session.send("Target.createTarget", {
    url: "https://admin.shopify.com",
    newWindow: true,
  });
  await session.detach();
  return targetId;
}

Then `browser_tabs` (action: list) and select the newly added entry — the tab that was not in the list before creation (new tabs are appended at the end); do not pick the first URL match, the developer may already have an admin tab open.

**In all cases: save the targetId — step 5 closes the window with it.**

• Lands on a store dashboard (`admin.shopify.com/store/...`) → authenticated.
• Redirects to `accounts.shopify.com` login → tell the user: "Log into the

Shopify admin in the verify window that just opened — the session persists." (profile mode: once per browser — each browser gets its own automation profile.) Wait for their confirmation, then re-check.

Keep the verify window open — the smoke test (step 5) reuses it.

4. Write the project config

1. `appHandle`: read `handle` from the project's `shopify.app.toml`. Multiple toml files (e.g. `shopify.app.<env>.toml`) → ask which one is the dev app. 2. `storeDomain`: ask the user for the dev store subdomain (`<storeDomain>.myshopify.com` → store part only, e.g. `store-seo-app-test`). 3. Write `.claude/shopify-verify.json`:

{
  "appHandle": "<from toml>",
  "storeDomain": "<from user>",
  "iframeSelector": "iframe[name=\"app-iframe\"]"
}

5. Smoke test

1. In the verify window from step 3, navigate to `https://admin.shopify.com/store/<storeDomain>/apps/<appHandle>`. 2. Wait for the app iframe; take a screenshot; confirm the app rendered.

• 404 → the app is not installed on this store; point the user to the dev

server output's install link.

• Iframe loads an error/tunnel page → the app's dev server is not running;

tell the user to check it (starting it is their job — never start or curl-probe it yourself). The verify loop needs it running, but setup itself is complete. 3. Report the result and delete the screenshot. 4. Close the verify window with `browser_run_code_unsafe` and the targetId saved in step 3 (never `browser_close` or close-by-index — both act on the current tab and misfire when the developer has many tabs open; if the