@wix/agent-skills 1.19.0 → 1.19.2

package/skills/wix-app/scripts/scan-a11y-review.cjs

@@ -0,0 +1,373 @@
+#!/usr/bin/env node
+'use strict';
+
+// oxlint-disable no-console preserve-caught-error
+
+/**
+ * Accessibility review for Editor React Components: one command, one JSON report.
+ *
+ *   node <SKILL_ROOT>/scripts/scan-a11y-review.cjs <component-dir | files...>
+ *
+ * Runs the jsx-a11y ESLint scanner and the Babel semantic/contract scanner in
+ * process, spawns the render audit (SSR + jsdom + axe-core) per component
+ * folder, and groups the findings by rule.
+ *
+ * Exit codes: 0 every scanner ran and found nothing, 1 findings, 2 a scanner
+ * could not run or could not load the component (never treat 2 as clean).
+ * Test hook: `A11Y_SKIP_RENDER=1` skips the render audit; the review is then
+ * inconclusive (exit 2) even with no findings.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const ROOT = process.cwd();
+const RENDER_SCRIPT = path.join(__dirname, 'scan-a11y-render.cjs');
+const RENDER_TIMEOUT_MS = Number(process.env.A11Y_RENDER_TIMEOUT_MS) || 20_000;
+const MAX_LOCATIONS_PER_GROUP = 5;
+const SEVERITY_RANK = { high: 0, medium: 1, low: 2 };
+const CONFIDENCE_RANK = { high: 0, medium: 1, low: 2, unknown: 3 };
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Arguments and discovery
+// ─────────────────────────────────────────────────────────────────────────────
+
+function parseArgs(argv) {
+  const options = { targets: [], render: process.env.A11Y_SKIP_RENDER !== '1' };
+  for (const arg of argv) {
+    if (arg.startsWith('--')) throw new Error(`Unknown option ${arg}`);
+    options.targets.push(arg);
+  }
+  return options;
+}
+
+const isSource = (name) =>
+  /\.(tsx|jsx)$/.test(name) && !/\.(stories|test|spec)\.[jt]sx$/.test(name);
+
+function listSources(dir, acc = []) {
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (entry.name !== 'node_modules') listSources(full, acc);
+    } else if (entry.isFile() && isSource(entry.name)) acc.push(full);
+  }
+  return acc;
+}
+
+function isComponentDir(dir) {
+  if (!fs.existsSync(dir) || !fs.statSync(dir).isDirectory()) return false;
+  const names = fs.readdirSync(dir);
+  return names.includes('component.tsx') || names.some((name) => name.endsWith('.props.ts'));
+}
+
+function findComponentDir(file) {
+  let dir = path.dirname(file);
+  for (let depth = 0; depth < 6 && !isComponentDir(dir); depth++) {
+    const parent = path.dirname(dir);
+    if (parent === dir) return path.dirname(file);
+    dir = parent;
+  }
+  return isComponentDir(dir) ? dir : path.dirname(file);
+}
+
+/** Expand targets (component folders, a components root, or files) into files and component folders. */
+function discoverFiles(targets) {
+  const files = new Set();
+  const componentDirs = new Set();
+  for (const target of targets) {
+    const resolved = path.resolve(target);
+    if (!fs.existsSync(resolved)) throw new Error(`Path not found: ${target}`);
+    if (fs.statSync(resolved).isDirectory()) {
+      if (isComponentDir(resolved)) componentDirs.add(resolved);
+      else {
+        for (const entry of fs.readdirSync(resolved, { withFileTypes: true })) {
+          const child = path.join(resolved, entry.name);
+          if (entry.isDirectory() && isComponentDir(child)) componentDirs.add(child);
+        }
+      }
+      for (const file of listSources(resolved)) files.add(file);
+    } else {
+      files.add(resolved);
+      componentDirs.add(findComponentDir(resolved));
+    }
+  }
+  return { files: [...files].toSorted(), componentDirs: [...componentDirs].toSorted() };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Scanners
+// ─────────────────────────────────────────────────────────────────────────────
+
+async function runScanner(name, load) {
+  const started = Date.now();
+  try {
+    const value = await load();
+    const parseErrors = (value.meta && value.meta.parseErrors) || [];
+    if (parseErrors.length) {
+      throw new Error(parseErrors.map((e) => `${e.file}: ${e.message}`).join('; '));
+    }
+    return { ok: true, ms: Date.now() - started, value };
+  } catch (error) {
+    const message = error && error.message ? error.message : String(error);
+    return { ok: false, ms: Date.now() - started, error: `${name}: ${message}` };
+  }
+}
+
+function eslintFindings(report) {
+  return report.findings.map((f) => ({
+    rule: f.rule,
+    source: 'eslint',
+    severity: 'high',
+    confidence: 'high',
+    message: f.message,
+    at: `${f.file}:${f.line}:${f.column}`,
+  }));
+}
+
+function semanticFindings(report) {
+  return report.findings.map((f) => {
+    const contract = f.sourceKind === 'contract';
+    const severity =
+      contract || f.confidence === 'high' ? 'high' : f.confidence === 'medium' ? 'medium' : 'low';
+    return {
+      rule: f.rule,
+      source: contract ? 'contract' : 'semantic',
+      severity,
+      confidence: f.confidence,
+      message: f.message,
+      detail: contract ? null : f.evidence,
+      at: `${f.file}:${f.line}:${f.column}`,
+    };
+  });
+}
+
+function runRenderChild(componentDir) {
+  const relativeDir = path.relative(ROOT, componentDir) || '.';
+  const started = Date.now();
+  const result = spawnSync(process.execPath, [RENDER_SCRIPT, componentDir], {
+    cwd: ROOT,
+    encoding: 'utf8',
+    timeout: RENDER_TIMEOUT_MS,
+    killSignal: 'SIGKILL',
+    maxBuffer: 8 * 1024 * 1024,
+    env: { ...process.env, NODE_ENV: process.env.NODE_ENV || 'development' },
+  });
+  const base = { componentDir: relativeDir, ms: Date.now() - started };
+
+  if (result.error && result.error.code === 'ETIMEDOUT') {
+    return {
+      ...base,
+      ok: false,
+      reason: 'timeout',
+      findings: [
+        {
+          rule: 'render-timeout',
+          source: 'render',
+          severity: 'high',
+          confidence: 'high',
+          message: `Rendering ${relativeDir} did not finish within ${RENDER_TIMEOUT_MS} ms. Rerun once; if it repeats, the first render never settles.`,
+        },
+      ],
+    };
+  }
+
+  let report = null;
+  try {
+    const lastLine = String(result.stdout || '')
+      .trim()
+      .split('\n')
+      .filter(Boolean)
+      .pop();
+    report = lastLine ? JSON.parse(lastLine) : null;
+  } catch {
+    report = null;
+  }
+  if (!report) {
+    const error = truncate(result.stderr || `exit ${result.status}`, 400);
+    return { ...base, ok: false, reason: 'crash', error, findings: [] };
+  }
+  if (!report.ok) {
+    return {
+      ...base,
+      ok: false,
+      reason: report.reason || 'error',
+      error: report.error || null,
+      findings: [],
+    };
+  }
+  return {
+    ...base,
+    ok: true,
+    entry: report.entry,
+    preview: report.preview,
+    ssr: report.ssr,
+    axeRules: report.axe ? report.axe.rulesRun : null,
+    notChecked: report.notChecked || [],
+    findings: report.findings.map((f) => ({
+      ...f,
+      source: 'render',
+      at: f.target ? `${relativeDir} ${f.target}` : relativeDir,
+    })),
+  };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Report
+// ─────────────────────────────────────────────────────────────────────────────
+
+function truncate(text, length) {
+  const compact = String(text || '').replace(/\s+/g, ' ');
+  return compact.length > length ? `${compact.slice(0, length - 1)}…` : compact;
+}
+
+/** One entry per (source, rule, message); repeated nodes become a count plus a few locations. */
+function groupFindings(findings, { capPerGroup = MAX_LOCATIONS_PER_GROUP } = {}) {
+  const groups = new Map();
+  for (const f of findings) {
+    const severity = f.severity in SEVERITY_RANK ? f.severity : 'medium';
+    const confidence = f.confidence in CONFIDENCE_RANK ? f.confidence : 'medium';
+    const key = `${f.source}|${f.rule}|${f.message}`;
+    if (!groups.has(key)) {
+      groups.set(key, {
+        rule: f.rule,
+        src: f.source,
+        sev: severity,
+        conf: confidence,
+        n: 0,
+        at: [],
+        html: f.html || null,
+        msg: f.message,
+        detail: f.detail || null,
+        helpUrl: f.helpUrl || null,
+      });
+    }
+    const group = groups.get(key);
+    group.n++;
+    if (f.at && group.at.length < capPerGroup && !group.at.includes(f.at)) group.at.push(f.at);
+    if (SEVERITY_RANK[severity] < SEVERITY_RANK[group.sev]) group.sev = severity;
+    if (CONFIDENCE_RANK[confidence] < CONFIDENCE_RANK[group.conf]) group.conf = confidence;
+  }
+  return [...groups.values()].toSorted(
+    (a, b) =>
+      SEVERITY_RANK[a.sev] - SEVERITY_RANK[b.sev] ||
+      CONFIDENCE_RANK[a.conf] - CONFIDENCE_RANK[b.conf] ||
+      b.n - a.n ||
+      a.rule.localeCompare(b.rule),
+  );
+}
+
+function renderLabel(result) {
+  if (result.ok) {
+    if (!result.ssr || !result.ssr.ok) return `render: ssr FAILED (${result.entry || '?'})`;
+    return `render ok (${result.entry || '?'}, axe ${result.axeRules ?? '-'})`;
+  }
+  return `render FAILED (${result.reason})`;
+}
+
+function buildSummary(groups, scanners, { renderEnabled = true } = {}) {
+  const counts = { high: 0, medium: 0, low: 0, groups: groups.length, findings: 0 };
+  for (const group of groups) {
+    counts[group.sev] += group.n;
+    counts.findings += group.n;
+  }
+  // A timeout is itself a finding; any other render failure (missing tooling,
+  // a module the audit cannot load) or a skipped render means the audit did
+  // not run, never clean.
+  const staticFailed = !scanners.eslint.ok || !scanners.semantic.ok;
+  const renderBroken =
+    !renderEnabled || scanners.render.some((r) => !r.ok && r.reason !== 'timeout');
+  const status =
+    staticFailed || renderBroken ? 'error' : counts.findings > 0 ? 'findings' : 'clean';
+  const severities = ['high', 'medium', 'low']
+    .filter((level) => counts[level] > 0)
+    .map((level) => `${counts[level]} ${level}`);
+  const line = [
+    `A11Y ${counts.groups} groups/${counts.findings} findings${severities.length ? ` (${severities.join(', ')})` : ''}`,
+    `eslint ${scanners.eslint.ok ? 'ok' : 'FAILED'}`,
+    `semantic ${scanners.semantic.ok ? 'ok' : 'FAILED'}`,
+    renderEnabled
+      ? scanners.render.map(renderLabel).join(' · ') || 'render: no component folder'
+      : 'render SKIPPED (inconclusive)',
+  ].join(' · ');
+  return { status, line, counts };
+}
+
+const computeExitCode = (summary) =>
+  summary.status === 'error' ? 2 : summary.counts.findings > 0 ? 1 : 0;
+
+async function review(options) {
+  const { files, componentDirs } = discoverFiles(options.targets);
+  // A wrong path (a typo, a parent folder) must never read as clean.
+  if (componentDirs.length === 0) {
+    throw new Error(
+      `No component folder under ${options.targets.join(', ')}: expected component.tsx or *.props.ts.`,
+    );
+  }
+
+  // ESLint rejects an empty file list; a folder with no JSX still gets its render audit.
+  const eslint = await runScanner('eslint', () =>
+    files.length ? require('./scan-a11y-eslint.cjs').scan(files) : { findings: [] },
+  );
+  const semantic = await runScanner('semantic', () =>
+    files.length ? require('./scan-a11y-code.cjs').scan(files) : { findings: [] },
+  );
+  const render = options.render ? componentDirs.map(runRenderChild) : [];
+
+  const findings = [
+    ...(eslint.ok ? eslintFindings(eslint.value) : []),
+    ...(semantic.ok ? semanticFindings(semantic.value) : []),
+    ...render.flatMap((r) => r.findings),
+  ];
+  const groups = groupFindings(findings);
+
+  const notChecked = new Set(options.render ? [] : ['render audit (skipped)']);
+  for (const r of render) {
+    for (const item of r.notChecked || []) notChecked.add(item);
+  }
+
+  const scanners = {
+    eslint: { ok: eslint.ok, ms: eslint.ms, error: eslint.error || null },
+    semantic: { ok: semantic.ok, ms: semantic.ms, error: semantic.error || null },
+    render: render.map(({ findings: _findings, notChecked: _notChecked, ...rest }) => rest),
+  };
+  const summary = buildSummary(groups, scanners, { renderEnabled: options.render });
+  return {
+    summary,
+    findings: groups,
+    scanners,
+    files: files.map((file) => path.relative(ROOT, file)),
+    notChecked: [...notChecked],
+    exitCode: computeExitCode(summary),
+  };
+}
+
+async function main() {
+  let options;
+  try {
+    options = parseArgs(process.argv.slice(2));
+    if (options.targets.length === 0) throw new Error('No component directory or files specified.');
+  } catch (error) {
+    console.error(
+      `${error.message}\nUsage: node <SKILL_ROOT>/scripts/scan-a11y-review.cjs <component-dir | files...>`,
+    );
+    process.exit(2);
+  }
+  try {
+    const report = await review(options);
+    console.log(JSON.stringify(report));
+    process.exit(report.exitCode);
+  } catch (error) {
+    console.log(
+      JSON.stringify({
+        summary: { status: 'error', line: error.message, counts: { findings: 0 } },
+        findings: [],
+      }),
+    );
+    process.exit(2);
+  }
+}
+
+module.exports = { review, discoverFiles, groupFindings, buildSummary, computeExitCode };
+
+if (require.main === module) main();

package/skills/wix-base44-connector/SKILL.md

@@ -23,8 +23,8 @@ they also surface from a search that began at the methods.
 
 In this skill:
 
-- **What are you building?** — route each feature to its identity: visitor token, admin token
-  in a backend function, or admin ad hoc in exec_tool
+- **What are you building?** — for visitors, for the owner, or management done for them —
+  decided per request from the user's intent, each on its own flow
 - **The helpers** — the `wx.*` loader every exec opens with
 - **Gather context** — `wx.context`, the report of what the site actually has
 - **Learn Wix** — find the APIs, learn their contracts
@@ -40,25 +40,41 @@ In this skill:
 
 ## What are you building?
 
-Choose the token by who the code acts for. A headless app can serve visitors, provide admin
-management tools, or do both.
-
-**A site for visitors** — use a visitor token for public reads and actions on behalf of the
-visitor, never the admin connector token. Call Wix directly from the browser through one shared
-visitor client (Write the code, below). Redirect sessions for Wix-hosted flows also require a
-visitor token minted for the headless OAuth app; see Visitor authentication and Wix-hosted flows below.
-Anyone can mint an anonymous visitor token from the
-OAuth app's public `clientId`; no visitor login is required. APIs for the "current visitor"
-use that token to identify whose data and state to access. This applies both to a standalone
-headless frontend and to a frontend extending an existing Wix site.
-
-**An admin tool for the owner** — use the admin connector token in backend functions implementing
-admin logic; keep it secret and server-side. The frontend calls those functions, not Wix with
-visitor tokens. A custom headless management site extending the Wix back office follows this
-flow too. Ad hoc management calls in `exec_tool` also use the admin token. Backend functions
-also handle work requiring the owner's permissions, such as webhooks, scheduled jobs, and
-explicitly authorized elevated operations. For an app with both visitor and admin features,
-keep each feature on its corresponding flow.
+Wix has two identities, visitor and admin, and each has its own flow. Decide which one every
+request is for before acting on it — from what the user wants, not from the technology:
+
+- **Visitor** — the people using the site: browsing, booking, buying, signing in as a member.
+  Visitor token, called from the browser through one shared visitor client.
+- **Admin, built** — a management surface of the owner's own: a custom view, a bulk operation,
+  an internal tool. Admin connector token, server-side in backend functions the frontend calls.
+- **Admin, done for them** — the user wants the business managed now, not an app: create the
+  products, change a setting, import the contacts. Admin token, ad hoc in exec_tool; nothing
+  ships in the app.
+
+The owner already has a full Wix dashboard for running the business — orders, products,
+bookings, settings, and more — so an admin build is a choice the user makes, not a gap to fill by
+default. When a request has both visitor and admin parts, each keeps its own flow.
+
+When the request doesn't say which, ask the user — in their terms (who the thing is for), not in
+technical ones (identities, tokens, flows). When you decide without asking, tell them what you
+chose the same way.
+
+The rules that follow from the split:
+
+- **Checkout runs on a visitor token, never the admin token** — including a checkout this app
+  creates for the visitor. The admin token *will* hand back a checkout URL, and that is the trap:
+  it belongs to the site rather than the buyer (no cart persistence, no abandoned-checkout
+  recovery, no attribution), and a redirect session refuses it outright (`403`). Returns reach
+  this app only from URLs in the OAuth app's redirect list (Visitor authentication and
+  Wix-hosted flows, below).
+- **No OAuth app yet is not a reason to use the admin token.** `wx.ensureOAuthApp` returns the
+  `clientId`, creating the app when the site has none — a visitor flow's first step. Anyone can
+  mint an anonymous visitor token from that public `clientId`; no visitor login is required.
+- **No login still means visitors.** `asServiceRole` governs this app's own data access and says
+  nothing about which identity Wix sees: a public page's Wix calls run on a visitor token. Reach
+  for the admin token because a feature is owner-side, never because nobody signs in.
+- **Owner-side work beyond pages** — webhooks, scheduled jobs, explicitly authorized elevated
+  operations — is admin flow too, in backend functions.
 
 ```
 visitor pages ──(visitor token)────────────────────────► wixapis.com
@@ -66,6 +82,11 @@ admin pages   ──► base44/functions/… ──(admin token)────►
 exec_tool     ──(admin token, ad hoc management)────────► wixapis.com
 ```
 
+**The connected site owns its payments.** Whatever the visitor buys is paid on the Wix-hosted page
+this app hands them off to, with the provider the site already has. Base44's
+`<available_payment_providers>` note is about checkout that Base44 hosts instead — it does not
+apply to these flows, and asks nothing of them, whichever providers it names or rules out.
+
 ## The helpers
 
 Research and probing run in exec_tool, and one loader opens every exec (execs share no state —
@@ -90,6 +111,7 @@ const wx = require(require("path").resolve(P));
 - `wx.bash(cmd)` — shell over saved files (GNU grep/sed; awk is mawk; no rg)
 - `wx.spec(docsUrl | code)` — a method's exact schema, plus the titles of the docs' own request examples saved at `examplesPath`; pass a hit's docsUrl (direct load), or raw code to query the index yourself
 - `wx.mgmtRecipes(q?)` — management-recipe index; no arg → categories, a word → matching recipes
+- `wx.ensureOAuthApp(token, { name, redirectUris, redirectDomains })` — the headless OAuth app, found by name or created, with the redirect lists merged into whatever it already allows; returns `{ clientId, created }`. `clientId` is what the browser mints visitor tokens from. Run it whenever `context` reports no OAuth app, or before any Wix-hosted flow that returns to this app — see Visitor authentication and Wix-hosted flows
 - `wx.installApp(appDefId, siteId, token)` — install a Wix app on the site (Apps Installer). If discovery finds an API whose app isn't installed on the site, install it first — that's a one-call prerequisite, **not** a reason to fall back to a hand-built alternative. `appDefId` from `search` or the Apps-Created-by-Wix table; `siteId` from `context` (the site report)
 
 Search makes one combined request across REST, management recipes, and Headless by default.
@@ -114,6 +136,10 @@ One report: installed apps **with ids** (incl. Stores' catalog version — V1 vs
 endpoints), the OAuth app id (**also the visitor `clientId`**), locale, currency, CMS collections.
 An empty report = bad token, never an empty site.
 
+No OAuth app in the report means the site has none **yet**. For anything a visitor operates,
+create it with `wx.ensureOAuthApp` — one call, returns the `clientId` the frontend mints visitor
+tokens from — and build the feature on the visitor flow.
+
 Reports over 4,000 characters are saved in full to a temporary Markdown file. The result includes
 its path, byte and line counts, and a heading outline. Read that file to inspect the site context.
 
@@ -228,7 +254,9 @@ Want to shape the result yourself? Pass raw code against the index (`lightIndex`
 await wx.spec(`
   const url = "<docsUrl from search/browse>";           // API method page, not a skill/article page
   const s = await getResourceSchemaByUrl(url);
-  const m = s.methods.find(x => x.docsUrl === url);
+  // A method URL resolves to exactly that method — take methods[0]. Don't match on docsUrl:
+  // the reader normalizes the url, so equality against the one you passed can miss.
+  const m = s.methods[0];
   return {
     call: m.publicUrl,                                       // callable https://www.wixapis.com/… URL
     body: m.requestBody?.content["application/json"].schema.properties,
@@ -327,13 +355,15 @@ return await wx.post("<a public read from Learn Wix>", { query: {} }, visitorTok
 
 **Any Wix-hosted flow that returns the visitor to your app needs the headless OAuth app's
 redirect config set.** This covers redirect sessions *and* sending a buyer to the Wix-hosted
-checkout `checkoutUrl` and back — any flow where Wix redirects to a URL on your app. Use the
-OAuth app's `clientId` from `wx.context()`; if the report has no OAuth app, create one with the
-admin connector token as shown below, then mint a visitor token from its `clientId` (anonymous
-visitors do not need to log in). **Always set `allowedRedirectUris` and `allowedRedirectDomains`
-when you create it** — an OAuth app created with a name only cannot complete any return, and the
-break is silent (create-checkout and the anonymous token still succeed) until a real buyer is
-redirected and stranded on Wix.
+checkout `checkoutUrl` and back — any flow where Wix redirects to a URL on your app.
+
+**Step one of any visitor flow: `wx.ensureOAuthApp` with this app's own URLs.** It returns the
+`clientId` the frontend mints visitor tokens from (anonymous visitors do not need to log in),
+creating the OAuth app when the site has none and adding your URLs to its lists when it already
+has one. Returns only complete for URLs in those lists, and a missing one breaks silently —
+create-checkout and the anonymous token still succeed — until a real buyer is redirected and
+stranded on Wix. It is idempotent by name: never create a second OAuth app for the same Base44
+app, or the first `clientId`'s returns stop working.
 
 ```js
 // Register BOTH of this app's own URLs — its preview URL and its published URL — so returns work
@@ -353,20 +383,14 @@ const returnDomains = appOrigins.map(origin => new URL(origin).hostname);
 // OAuth redirect configuration: exact login URLs versus domains for other returns.
 // https://dev.wix.com/docs/go-headless/authentication/setup/allow-redirect-uris-and-domains.md
 const { accessToken: adminToken } = await base44.asServiceRole.connectors.getConnection("wix");
-const { oAuthApp } = await wx.post("https://www.wixapis.com/oauth-app/v1/oauth-apps", {
-  oAuthApp: {
-    name: "My App",
-    // Login callbacks: the authorization request's redirect URI must match exactly.
-    allowedRedirectUris: loginCallbacks,
-    // Returns from Wix-hosted flows: hostnames only, allowing URLs under each domain.
-    allowedRedirectDomains: returnDomains,
-  },
-}, adminToken);
-const clientId = oAuthApp.id; // Public visitor client ID, used by the frontend client above.
-
-// If destinations change later, update this OAuth app rather than creating another.
-// Read its existing lists and merge new entries before updating, preserving old entries.
-// https://dev.wix.com/docs/api-reference/business-management/headless/oauth-apps/update-oauth-app.md
+const { clientId, created } = await wx.ensureOAuthApp(adminToken, {
+  name: "My App",                     // this app's name; the lookup key on later runs
+  redirectUris: loginCallbacks,       // login callbacks: matched exactly by the auth request
+  redirectDomains: returnDomains,     // returns from Wix-hosted flows: hostnames only
+});
+// clientId is the public visitor client id the frontend client above mints from.
+// When destinations change later — a custom domain, a renamed app — call this again with the
+// new URLs: it updates the same OAuth app and preserves the entries already there.
 
 ```
 

package/skills/wix-base44-connector/scripts/utils.cjs

@@ -353,9 +353,13 @@ async function spec(arg) {
   const code = /^async function/.test(s) ? s
     : /^https:\/\/dev\.wix\.com\/docs\//.test(s) ? "async function(){ return await getResourceSchemaByUrl(" + JSON.stringify(s) + "); }"
     : "async function(){ " + s + " }";
-  const { result } = await post("https://mcp.wix.com/api/code-mode/search", { code });
+  const { result, error } = await post("https://mcp.wix.com/api/code-mode/search", { code });
+  // The envelope is 200 even when the query throws — the cause is in `error`, not the status.
+  // Surfacing it matters: swallowing it turns "your code threw" into "nothing matched".
+  if (error)
+    return { error, note: "the query threw — read the message and fix the code; don't re-send it unchanged" };
   if (result == null || (Array.isArray(result) && !result.length))
-    return { result, note: "empty — the query missed the shape; match your docsUrl against s.methods[].docsUrl" };
+    return { result, note: "the query ran but matched nothing — widen it, or check the url resolves" };
   const text = JSON.stringify(result, null, 1);
   if (text.length <= BUDGET) return result;
   let h = 5381;
@@ -424,4 +428,36 @@ async function installApp(appDefId, siteId, token) {
     { tenant: { tenantType: "SITE", id: siteId }, appInstance: { appDefId } }, token);
 }
 
-module.exports = { req, post, get, patch, put, del, clip, context, browse, search, page, bash, spec, mgmtRecipes, installApp };
+// The headless OAuth app: the visitor client id, and the redirect config every Wix-hosted
+// return needs. Idempotent by name — a site reached by the "connect an existing site" flow
+// has none, and creating a second one for the same app strands the first app's returns.
+// Redirect lists are merged, never replaced: an app that already serves a custom domain
+// keeps it when a preview URL is added.
+async function ensureOAuthApp(token, { name, redirectUris = [], redirectDomains = [] }) {
+  const { oAuthApps = [] } = await post(
+    "https://www.wixapis.com/oauth-app/v1/oauth-apps/query", { query: {} }, token);
+  const existing = oAuthApps.find((a) => a.name === name);
+  const merge = (a = [], b = []) => [...new Set([...a, ...b])];
+  if (!existing) {
+    const { oAuthApp } = await post("https://www.wixapis.com/oauth-app/v1/oauth-apps", {
+      oAuthApp: { name, allowedRedirectUris: redirectUris, allowedRedirectDomains: redirectDomains },
+    }, token);
+    return { clientId: oAuthApp.id, created: true, oAuthApp };
+  }
+  const allowedRedirectUris = merge(existing.allowedRedirectUris, redirectUris);
+  const allowedRedirectDomains = merge(existing.allowedRedirectDomains, redirectDomains);
+  const unchanged =
+    allowedRedirectUris.length === (existing.allowedRedirectUris || []).length &&
+    allowedRedirectDomains.length === (existing.allowedRedirectDomains || []).length;
+  if (unchanged) return { clientId: existing.id, created: false, oAuthApp: existing };
+  // The update docs disagree with themselves on the mask field (prose says `paths`, the
+  // curl example says `path`); send both so the call does not silently no-op.
+  const paths = ["allowedRedirectUris", "allowedRedirectDomains"];
+  const { oAuthApp } = await patch(
+    `https://www.wixapis.com/oauth-app/v1/oauth-apps/${existing.id}`,
+    { oAuthApp: { id: existing.id, allowedRedirectUris, allowedRedirectDomains },
+      mask: { paths, path: paths.join(",") } }, token);
+  return { clientId: (oAuthApp || existing).id, created: false, oAuthApp: oAuthApp || existing };
+}
+
+module.exports = { req, post, get, patch, put, del, clip, context, browse, search, page, bash, spec, mgmtRecipes, installApp, ensureOAuthApp };