@wix/agent-skills 1.21.0 → 1.23.0

package/skills/wix-headless-fast/install/context.mjs

@@ -0,0 +1,126 @@
+// The site context of a project folder — the one place that says which site a call targets.
+//
+//   node <SKILL_ROOT>/install/context.mjs [--refresh] [--no-pull]     (prints one JSON object)
+//
+// Two identities live in a Wix project and are the same site almost always:
+//   deploy  — `wix.config.json` (`siteId`, `appId`): where `wix release` uploads. The CLI's business.
+//   content — `.env.local` (`WIX_CLIENT_ID`, what `wix env pull` writes): the app the SDK client
+//             runs as, on every stack (the Astro integration reads WIX_CLIENT_ID from the env and
+//             never the config; the other stacks get it copied into src/wix/config.ts by deploy.mjs).
+// They differ on a MIGRATION PREVIEW: a project whose config points at a fresh site created only to
+// host the deployment, while `.env.local` carries the credentials of the site being migrated (the
+// parent) and says so. Then every admin, discovery and seed call targets the parent, the SDK client
+// is the parent's, and only the release goes to the child. Completing the migration is a CLI step
+// that does not exist yet; this module only reads the state.
+//
+// `env pull` runs here when `.env.local` is missing (or --refresh): it is the source of the content
+// identity, and the Astro build refuses to run without it. Non-interactive (CI=1); a failure is
+// reported in `pullError` and the config's ids stand in, so a caller can still work offline.
+import { spawnSync } from "node:child_process";
+import { copyFileSync, existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+// The variables `wix env pull` writes for a migration preview. The names are the platform's and are
+// spelled once, here.
+export const ENV = {
+  clientId: "WIX_CLIENT_ID",
+  parentSiteId: "WIX_MIGRATION_PARENT_SITE_ID",
+  migration: "WIX_MIGRATION",
+};
+
+/** KEY=value lines of a dotenv file, quotes stripped; null when the file is absent. */
+export function readEnvFile(file) {
+  if (!existsSync(file)) return null;
+  const out = {};
+  for (const raw of readFileSync(file, "utf8").split(/\r?\n/)) {
+    const line = raw.trim();
+    if (!line || line.startsWith("#")) continue;
+    const eq = line.indexOf("=");
+    if (eq === -1) continue;
+    const key = line.slice(0, eq).trim().replace(/^export\s+/, "");
+    let value = line.slice(eq + 1).trim();
+    if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+      value = value.slice(1, -1).replace(/\\"/g, '"');
+    }
+    out[key] = value;
+  }
+  return out;
+}
+
+export function readWixConfig(cwd) {
+  const file = join(cwd, "wix.config.json");
+  if (!existsSync(file)) return null;
+  try { return JSON.parse(readFileSync(file, "utf8")); } catch { return null; }
+}
+
+const truthy = (v) => typeof v === "string" && /^(1|true|yes|on)$/i.test(v.trim());
+
+const ENV_PULL = ["-y", "@wix/cli@latest", "env", "pull"];
+const runPull = (dir) => spawnSync("npx", ENV_PULL, { cwd: dir, env: { ...process.env, CI: "1" }, encoding: "utf8", timeout: 180_000 });
+
+/**
+ * `wix env pull` into `cwd/.env.local`. The CLI mounts `env` only once the folder reads as an Astro
+ * project (an astro.config.* file, or `site.outputDirectory` in the config); a folder that holds just
+ * the downloaded `wix.config.json` gets "unknown command 'env'". Then the pull runs in a temp folder
+ * holding a copy of the config and an empty astro.config.mjs, and the `.env.local` comes back here.
+ */
+export function pullEnv(cwd) {
+  const envFile = join(cwd, ".env.local");
+  let r = runPull(cwd);
+  if (r.status === 0 && existsSync(envFile)) return { ok: true, via: "in place" };
+  const notAProjectYet = /unknown command 'env'/.test(`${r.stderr}${r.stdout}`);
+  if (notAProjectYet) {
+    const tmp = mkdtempSync(join(tmpdir(), "wix-env-pull-"));
+    try {
+      copyFileSync(join(cwd, "wix.config.json"), join(tmp, "wix.config.json"));
+      writeFileSync(join(tmp, "astro.config.mjs"), "");
+      r = runPull(tmp);
+      if (r.status === 0 && existsSync(join(tmp, ".env.local"))) {
+        copyFileSync(join(tmp, ".env.local"), envFile);
+        return { ok: true, via: "stub project" };
+      }
+    } finally {
+      rmSync(tmp, { recursive: true, force: true });
+    }
+  }
+  return { ok: false, error: (r.stderr || r.stdout || "env pull produced no .env.local — is the Wix CLI logged in? (npx @wix/cli@latest whoami)").trim().slice(-400) };
+}
+
+/**
+ * `{ deploy: { siteId, appId }, content: { siteId, clientId }, migration: { active, parentSiteId },
+ *    env: { file, present, pulled }, pullError?, warnings: [] }`.
+ * `pull`: "auto" (default) pulls when `.env.local` is missing; true always; false never.
+ */
+export function siteContext({ cwd = process.cwd(), pull = "auto" } = {}) {
+  const config = readWixConfig(cwd) ?? {};
+  const deploy = { siteId: config.siteId ?? config.projectId ?? null, appId: config.appId ?? null };
+  const envFile = join(cwd, ".env.local");
+  let pulled = false, pullError;
+  if (deploy.siteId && (pull === true || (pull === "auto" && !existsSync(envFile)))) {
+    const r = pullEnv(cwd);
+    if (r.ok) pulled = r.via;
+    else pullError = r.error;
+  }
+  const env = readEnvFile(envFile) ?? {};
+  const parentSiteId = env[ENV.parentSiteId] || null;
+  const active = !!parentSiteId && (truthy(env[ENV.migration]) || env[ENV.migration] === undefined);
+  const migration = { active, parentSiteId: active ? parentSiteId : null };
+  const clientId = env[ENV.clientId] || deploy.appId;
+  const content = { siteId: active ? parentSiteId : deploy.siteId, clientId };
+  const warnings = [];
+  if (env[ENV.clientId] && deploy.appId && env[ENV.clientId] !== deploy.appId && !active) {
+    warnings.push(`.env.local ${ENV.clientId} differs from wix.config.json appId and no migration is declared — the SDK client runs as the env's app, the release goes to the config's site`);
+  }
+  if (active && migration.parentSiteId === deploy.siteId) {
+    warnings.push("the migration's parent site is the deploy site itself — nothing is being migrated");
+  }
+  return { deploy, content, migration, env: { file: envFile, present: Object.keys(env).length > 0, pulled }, ...(pullError ? { pullError } : {}), warnings };
+}
+
+// ---- CLI ----------------------------------------------------------------------------------------
+if (process.argv[1] && /context\.mjs$/.test(process.argv[1])) {
+  const argv = process.argv.slice(2);
+  const pull = argv.includes("--no-pull") ? false : argv.includes("--refresh") ? true : "auto";
+  console.log(JSON.stringify(siteContext({ pull }), null, 2));
+}

package/skills/wix-headless-fast/install/deploy.mjs

@@ -43,21 +43,26 @@ import {
 } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+import { templatesDir } from "./templates.mjs";
+import { syncLockRoot } from "./lock.mjs";
+import { siteContext } from "./context.mjs";
 
 const SKILL_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
-const REF = join(SKILL_ROOT, "references");
+// The shipped code: the repository's templates/ (a checkout, the cache, or fetched now).
+const REF = templatesDir();
 const PROJECT = process.cwd();
 const SRC = join(PROJECT, "src");
 const CONFIG_TS = join(SRC, "wix", "config.ts");
 const PKG_JSON = join(PROJECT, "package.json");
 
-// The vertical registry: every directory under references/ that ships an app/ is a vertical.
+// The vertical registry: every directory under templates/ that ships an app/ is a vertical.
 const VERTICALS = readdirSync(REF, { withFileTypes: true })
   .filter(
     (d) =>
       d.isDirectory() &&
       existsSync(join(REF, d.name, "app")) &&
-      d.name !== "shared",
+      d.name !== "shared" &&
+      d.name !== "blank",
   )
   .map((d) => d.name);
 
@@ -73,12 +78,14 @@ const SHARED_DEPS = {
 };
 const CAPABILITY_DEPS = {
   "media-upload": {
-    // All shipped Astro locks already carry @wix/media >= 1.0.271 transitively. Keep this
-    // range compatible with them, then promote it to a root lock dependency below.
     "@wix/media": "^1.0.271",
     "@wix/essentials": "^1.0.10",
   },
+  "site-search": {
+    "@wix/search": "^1.0.90",
+  },
 };
+const SITE_SEARCH = join("shared", "capabilities", "site-search");
 const VERTICAL_DEPS = {
   storefront: {
     core: {
@@ -158,6 +165,19 @@ const VERTICAL_DEPS = {
       "@wix/redirects": "^1.0.125",
     },
   },
+  faq: {
+    core: {
+      "@wix/faq": "^1.0.76",
+    },
+    // no astro block: the FAQ page is a plain page (no wixMetadata item routing); its JSON-LD is inline
+  },
+  donations: {
+    core: {
+      "@wix/donations": "^1.0.64",
+      "@wix/ecom": "^1.0.2454",
+      "@wix/redirects": "^1.0.125",
+    },
+  },
 };
 
 const COPY = { recursive: true, force: false, errorOnExist: false };
@@ -179,7 +199,7 @@ const flagArgs = new Set(
 );
 const requested = [...new Set(argv.filter((a) => !flagArgs.has(a)))];
 
-const result = { stack, verticals: [], skillRoot: SKILL_ROOT };
+const result = { stack, verticals: [], skillRoot: SKILL_ROOT, templates: REF };
 
 if (!["astro", "react", "lib", "static"].includes(stack)) {
   console.log(
@@ -209,6 +229,27 @@ if (!Array.isArray(uploadPolicies)) {
   console.log(JSON.stringify({ error: "plan.capabilities.mediaUpload.policies must be an array" }));
   process.exit(1);
 }
+// Site search is on when the plan carries the entry (`{}` is enough; `true` too). Its fields are
+// data for the generated config; the shipped core drops unknown type names, so only shapes are checked.
+const siteSearchEntry = plan.capabilities?.siteSearch;
+const siteSearch = siteSearchEntry === true ? {} : siteSearchEntry && typeof siteSearchEntry === "object" ? siteSearchEntry : null;
+if (siteSearchEntry != null && siteSearchEntry !== false && !siteSearch) {
+  console.log(JSON.stringify({ error: "plan.capabilities.siteSearch must be an object (or true)" }));
+  process.exit(1);
+}
+if (siteSearch) {
+  const strings = (v) => Array.isArray(v) && v.every((x) => typeof x === "string");
+  const map = (v) => v === undefined || (v && typeof v === "object" && !Array.isArray(v) && Object.values(v).every((x) => typeof x === "string"));
+  if ((siteSearch.types !== undefined && !strings(siteSearch.types)) || !map(siteSearch.routes) || !map(siteSearch.labels)) {
+    console.log(JSON.stringify({ error: "plan.capabilities.siteSearch: types must be string[]; routes and labels must be objects of strings" }));
+    process.exit(1);
+  }
+}
+// The generated file is data only; the shipped core resolves defaults (types, routes, labels) from it.
+const siteSearchConfigSource = () =>
+  `// Generated by wix-headless-fast install/deploy.mjs from plan.capabilities.siteSearch.\n` +
+  `// Edit the plan and redeploy. Defaults for anything omitted are in search-core.ts (resolveConfig).\n` +
+  `export const siteSearchPlan = ${JSON.stringify(siteSearch, null, 2)};\n`;
 // ---- static stack: the REST layer, composed flat and stripped ------------------------------------
 if (stack === "static") {
   const { spawnSync } = await import("node:child_process");
@@ -216,10 +257,9 @@ if (stack === "static") {
   const OUT = outDir ? resolve(PROJECT, outDir) : PROJECT;
   const JS = join(OUT, "js", "wix");
   result.out = outDir ?? ".";
-  let clientId = clientIdFlag;
-  if (!clientId && existsSync(join(PROJECT, "wix.config.json"))) {
-    clientId = JSON.parse(readFileSync(join(PROJECT, "wix.config.json"), "utf8")).appId ?? null;
-  }
+  // The client id the browser mints visitor tokens with: --client-id, else the CONTENT app from
+  // .env.local (`wix env pull`; on a migration preview the parent site's app), else the config's appId.
+  let clientId = clientIdFlag ?? (existsSync(join(PROJECT, "wix.config.json")) ? siteContext({ cwd: PROJECT }).content.clientId : null);
   if (!clientId) {
     console.log(JSON.stringify({ error: "static stack needs the public OAuth client id — run `npm create @wix/new@latest init` here first, or pass --client-id" }));
     process.exit(1);
@@ -231,19 +271,23 @@ if (stack === "static") {
   }
   // Only files that aren't there yet — a re-run restores, never clobbers (same as the copy below).
   cpSync(join(REF, "shared", "rest"), JS, COPY);
-  for (const vertical of requested) {
-    cpSync(join(REF, vertical, "rest"), JS, COPY);
+  // Every layer with a rest/ twin: the requested verticals, plus the site-search capability when the
+  // plan turns it on (same shape — rest/ beside app/wix/<name>/ — at templates/shared/capabilities).
+  const layers = requested.map((vertical) => [vertical, join(REF, vertical)]);
+  if (siteSearch) layers.push(["site-search", join(REF, SITE_SEARCH)]);
+  for (const [vertical, root] of layers) {
+    cpSync(join(root, "rest"), JS, COPY);
     // The vertical's transport-agnostic core: types, every *-core.ts, and every *-store.ts under its
     // app/wix/<vertical>/ — the stores are the hooks' logic without React, over the same function
     // names the REST twin exports, so they run against it unchanged.
-    const appWix = join(REF, vertical, "app", "wix", vertical);
+    const appWix = join(root, "app", "wix", vertical);
     for (const f of readdirSync(appWix)) {
       // Every vertical has a types.ts; flat in one folder they would collide, so each lands as
       // <vertical>-types.ts and the vertical's own files are pointed at it below.
       if (f === "types.ts") cpSync(join(appWix, f), join(JS, `${vertical}-types.ts`), COPY);
       else if (f.endsWith("-core.ts") || f.endsWith("-store.ts")) cpSync(join(appWix, f), join(JS, f), COPY);
     }
-    const own = new Set([...readdirSync(join(REF, vertical, "rest")), ...readdirSync(appWix)].filter((f) => f.endsWith(".ts") && f !== "types.ts"));
+    const own = new Set([...readdirSync(join(root, "rest")), ...readdirSync(appWix)].filter((f) => f.endsWith(".ts") && f !== "types.ts"));
     for (const f of own) {
       const fp = join(JS, f);
       if (!existsSync(fp)) continue;
@@ -251,7 +295,12 @@ if (stack === "static") {
       const fixed = src.replace(/from\s+"\.\/types(?:\.js)?"/g, `from "./${vertical}-types.js"`);
       if (fixed !== src) writeFileSync(fp, fixed);
     }
-    result.verticals.push(vertical);
+    if (VERTICALS.includes(vertical)) result.verticals.push(vertical);
+  }
+  if (siteSearch) {
+    // The REST twin imports the plan as data from beside it (shared/rest already owns config.ts).
+    writeFileSync(join(JS, "site-search-config.generated.ts"), siteSearchConfigSource());
+    result.capabilities = { ...result.capabilities, siteSearch: true };
   }
   // Browser ESM resolves nothing: every relative import needs its .js. The rest/ files are written
   // that way; the files borrowed from app/wix/ are bundler-style and get the suffix here.
@@ -284,7 +333,7 @@ if (stack === "static") {
   result.js = `${outDir ? outDir.replace(/\/$/, "") + "/" : ""}js/wix/*.js`;
   // The note lists what actually landed, so it holds for every vertical (and several at once).
   const stores = readdirSync(JS).filter((f) => f.endsWith("-store.js")).map((f) => `./js/wix/${f}`);
-  const dataFiles = readdirSync(JS).filter((f) => f.endsWith(".js") && !f.endsWith("-store.js") && !f.endsWith("-core.js") && !f.endsWith("-types.js") && !["client.js", "config.js", "media.js"].includes(f)).map((f) => `./js/wix/${f}`);
+  const dataFiles = readdirSync(JS).filter((f) => f.endsWith(".js") && !f.endsWith("-store.js") && !f.endsWith("-core.js") && !f.endsWith("-types.js") && !f.endsWith(".generated.js") && !["client.js", "config.js", "media.js"].includes(f)).map((f) => `./js/wix/${f}`);
   result.note = `import the data layer (${dataFiles.join(", ")})${stores.length ? ` and the stores (${stores.join(", ")})` : ""} relative to ${outDir ?? "the project root"} in a <script type="module">; the .ts beside them are the same files with types, for reading; point wix.config.json site.outputDirectory at "./${outDir ?? "."}"`;
   console.log(JSON.stringify(result));
   process.exit(0);
@@ -317,11 +366,20 @@ if (uploadPolicies.length) {
   cpSync(join(REF, "shared", "capabilities", "media-upload", "app"), SRC, COPY);
   cpSync(join(REF, "shared", "capabilities", "media-upload", "app-astro"), SRC, COPY);
 }
+// Site search ships like a vertical (data layer, stores, hooks, components, a search page) at a
+// disjoint path (src/wix/site-search/, src/components/site-search/, …), so the same per-stack rule
+// applies: lib takes only app/wix/, astro adds app-astro/.
+if (siteSearch) {
+  if (stack === "lib") cpSync(join(REF, SITE_SEARCH, "app", "wix"), join(SRC, "wix"), COPY);
+  else cpSync(join(REF, SITE_SEARCH, "app"), SRC, COPY);
+  if (stack === "astro") cpSync(join(REF, SITE_SEARCH, "app-astro"), SRC, COPY);
+}
 
 const unknown = requested.filter((v) => !VERTICALS.includes(v));
 // lib: only @wix/sdk from the shared deps — the Tailwind pair serves the components, which don't ship there.
 const wantedDeps = stack === "lib" ? { "@wix/sdk": SHARED_DEPS["@wix/sdk"] } : { ...SHARED_DEPS };
 if (uploadPolicies.length) Object.assign(wantedDeps, CAPABILITY_DEPS["media-upload"]);
+if (siteSearch) Object.assign(wantedDeps, CAPABILITY_DEPS["site-search"]);
 for (const vertical of requested.filter((v) => VERTICALS.includes(v))) {
   if (stack === "lib") cpSync(join(REF, vertical, "app", "wix"), join(SRC, "wix"), COPY);
   else cpSync(join(REF, vertical, "app"), SRC, COPY);
@@ -349,6 +407,15 @@ if (uploadPolicies.length) {
   );
   result.capabilities = { mediaUpload: uploadPolicies.map((policy) => policy.id) };
 }
+if (siteSearch) {
+  // The SDK transport imports the plan as data from beside it; defaults resolve in the shipped core.
+  writeFileSync(join(SRC, "wix", "site-search", "config.generated.ts"), siteSearchConfigSource());
+  result.capabilities = { ...result.capabilities, siteSearch: true };
+  if (siteSearch.install) {
+    // Indexing needs the Wix Site Search app on the site — a site mutation the deploy never makes.
+    result.note = [result.note, "siteSearch.install: run `node <SKILL_ROOT>/templates/shared/capabilities/site-search/seed/install.mjs` from the project root after the seed (results appear about half a minute later)"].filter(Boolean).join("; ");
+  }
+}
 
 // ---- dependency patch (fill-only) ----------------------------------------------------------------
 if (result.verticals.length && existsSync(PKG_JSON)) {
@@ -362,13 +429,6 @@ if (result.verticals.length && existsSync(PKG_JSON)) {
   if (added.length)
     writeFileSync(PKG_JSON, JSON.stringify(pkg, null, 2) + "\n");
   result.depsAdded = added.map(([name]) => name);
-  if (added.length)
-    result.note = [
-      result.note,
-      "run `npm install --ignore-scripts` to pick up depsAdded",
-    ]
-      .filter(Boolean)
-      .join("; ");
 } else if (result.verticals.length) {
   result.depsAdded = [];
   result.note = [
@@ -379,54 +439,20 @@ if (result.verticals.length && existsSync(PKG_JSON)) {
     .join("; ");
 }
 
-// ---- shipped lockfile (single vertical only) ------------------------------------------------------
-// A pre-resolved package-lock.json covering the scaffold + this vertical's deps ships at
-// references/<vertical>/lock/<stack>/package-lock.json. Placing it lets `npm ci` skip the whole
-// resolution phase (seconds instead of minutes). URLs are canonical registry.npmjs.org form —
-// npm substitutes the locally configured registry (mirrors/proxies) at fetch time. Placed only
-// when the project has no lock of its own; if it ever drifts out of sync, `npm ci` fails fast
-// and the `|| npm install` fallback self-heals.
+// ---- the project's lockfile ---------------------------------------------------------------------
+// A project created from a composed template (templates/<vertical>/project) carries that
+// template's package-lock.json, so `npm ci` installs it without resolving. When this run added
+// dependencies to package.json, the lock's root entry is brought in line where the tree already
+// holds the package (install/lock.mjs); anything the tree lacks makes `npm ci` fail fast and the
+// `|| npm install` fallback resolve it. A project without a lock installs with `npm install`.
 const PROJECT_LOCK = join(PROJECT, "package-lock.json");
-if (
-  result.verticals.length === 1 &&
-  existsSync(PKG_JSON) &&
-  !existsSync(PROJECT_LOCK)
-) {
-  const shippedLock = join(
-    REF,
-    result.verticals[0],
-    "lock",
-    stack,
-    "package-lock.json",
-  );
-  if (existsSync(shippedLock)) {
-    cpSync(shippedLock, PROJECT_LOCK);
-    if (uploadPolicies.length) {
-      // The supplied per-vertical lock already resolves Media + Essentials transitively. Add
-      // them to its root package entry too, so npm ci accepts package.json's new direct
-      // dependency without falling back to a slow dependency-resolution install.
-      const lock = JSON.parse(readFileSync(PROJECT_LOCK, "utf8"));
-      lock.packages ??= {};
-      lock.packages[""] ??= {};
-      lock.packages[""].dependencies ??= {};
-      const rootDeps = lock.packages[""].dependencies;
-      for (const [name, range] of Object.entries(CAPABILITY_DEPS["media-upload"])) {
-        if (!lock.packages?.[`node_modules/${name}`]) {
-          result.lockCapability = `UNPATCHED — supplied lock lacks ${name}; npm install will resolve it`;
-          break;
-        }
-        rootDeps[name] = range;
-      }
-      writeFileSync(PROJECT_LOCK, JSON.stringify(lock, null, 2) + "\n");
-      if (!result.lockCapability) result.lockCapability = "media_upload_promoted";
-    }
-    result.lockDeployed = true;
-    result.note = [
-      result.note,
-      "install with `npm ci --ignore-scripts || npm install --ignore-scripts`",
-    ]
-      .filter(Boolean)
-      .join("; ");
+if (result.verticals.length && existsSync(PKG_JSON)) {
+  if (existsSync(PROJECT_LOCK)) {
+    const sync = syncLockRoot(PROJECT);
+    if (sync && (sync.promoted.length || sync.missing.length)) result.lock = sync;
+    result.note = [result.note, "install with `npm ci --ignore-scripts || npm install --ignore-scripts`"].filter(Boolean).join("; ");
+  } else if (result.depsAdded?.length) {
+    result.note = [result.note, "run `npm install --ignore-scripts` to pick up depsAdded"].filter(Boolean).join("; ");
   }
 }
 
@@ -455,12 +481,15 @@ if (stack === "astro" && result.verticals.length && existsSync(ASTRO_CONFIG)) {
 
 // ---- ready-made links -----------------------------------------------------------------------------
 // Emit the siteId and the dashboard deep links so nothing downstream re-derives or retypes them.
+// The site the links point at is the CONTENT site — the parent on a migration preview, where the
+// config's site only hosts the deployment (install/context.mjs).
 const WIX_CONFIG = join(PROJECT, "wix.config.json");
-if (existsSync(WIX_CONFIG)) {
-  const config = JSON.parse(readFileSync(WIX_CONFIG, "utf8"));
-  const siteId = config.siteId ?? config.projectId;
+const ctx = existsSync(WIX_CONFIG) ? siteContext({ cwd: PROJECT }) : null;
+if (ctx) {
+  const siteId = ctx.content.siteId;
   if (siteId) {
     result.siteId = siteId;
+    if (ctx.migration.active) result.migration = { parentSiteId: ctx.migration.parentSiteId, deploySiteId: ctx.deploy.siteId };
     result.dashboardUrl = `https://manage.wix.com/dashboard/${siteId}`;
     if (result.verticals.includes("storefront")) {
       result.productsUrl = `https://manage.wix.com/dashboard/${siteId}/wix-stores/products`;
@@ -479,13 +508,10 @@ if (!requested.length) {
 // ---- client ids ---------------------------------------------------------------------------------
 // The shared data client is ambient on managed Astro. Members are different: their shipped
 // custom credential flow always needs an explicit public OAuth client, including on Astro.
-let clientId = clientIdFlag;
-if (!clientId && existsSync(join(PROJECT, "wix.config.json"))) {
-  // On a Wix-managed project the public OAuth client id IS the appId.
-  clientId =
-    JSON.parse(readFileSync(join(PROJECT, "wix.config.json"), "utf8")).appId ??
-    null;
-}
+// --client-id, else the CONTENT app: .env.local's WIX_CLIENT_ID (what `wix env pull` writes — on a
+// migration preview the parent site's app, the one the Astro integration itself runs as), else the
+// config's appId. Never the config first: on a preview that is the deploy-only child app.
+const clientId = clientIdFlag ?? ctx?.content.clientId ?? null;
 if (stack === "react" || stack === "lib") {
   if (clientId) {
     const current = readFileSync(CONFIG_TS, "utf8");

package/skills/wix-headless-fast/install/lock.mjs

@@ -0,0 +1,55 @@
+// Keep a project's package-lock.json valid for `npm ci` after package.json gained dependencies.
+// `npm ci` refuses a lock whose root entry disagrees with package.json. When the dependency deploy
+// added is already in the lock's tree (pulled in by something else), declaring it in the root entry
+// too is all `npm ci` needs; a dependency the tree lacks is left for `npm install` to resolve.
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+const parse = (v) => {
+  const m = String(v).match(/^(\d+)\.(\d+)\.(\d+)/);
+  return m ? m.slice(1).map(Number) : null;
+};
+const cmp = (a, b) => a[0] - b[0] || a[1] - b[1] || a[2] - b[2];
+
+// The ranges deploy writes: exact, ^x.y.z, ~x.y.z, >=x.y.z. Anything else is "not known to fit".
+export function satisfies(version, range) {
+  const v = parse(version);
+  const m = String(range).trim().match(/^(\^|~|>=)?\s*v?(\d+\.\d+\.\d+)/);
+  if (!v || !m) return false;
+  const r = parse(m[2]);
+  const op = m[1] ?? "";
+  if (op === "") return cmp(v, r) === 0;
+  if (cmp(v, r) < 0) return false;
+  if (op === ">=") return true;
+  if (op === "~") return v[0] === r[0] && v[1] === r[1];
+  // caret: same major; for 0.x, same minor
+  return r[0] > 0 ? v[0] === r[0] : v[0] === 0 && v[1] === r[1];
+}
+
+// Returns null when there is no lock; else {promoted, missing}. Writes the lock only when it changed.
+export function syncLockRoot(projectDir) {
+  const lockPath = join(projectDir, "package-lock.json");
+  const pkgPath = join(projectDir, "package.json");
+  if (!existsSync(lockPath) || !existsSync(pkgPath)) return null;
+  const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+  const lock = JSON.parse(readFileSync(lockPath, "utf8"));
+  lock.packages ??= {};
+  const root = (lock.packages[""] ??= {});
+  const promoted = [], missing = [];
+  let changed = false;
+  for (const field of ["dependencies", "devDependencies"]) {
+    for (const [name, range] of Object.entries(pkg[field] ?? {})) {
+      if (root[field]?.[name] === range) continue;
+      const inTree = lock.packages[`node_modules/${name}`];
+      if (inTree && satisfies(inTree.version, range)) {
+        (root[field] ??= {})[name] = range;
+        promoted.push(name);
+        changed = true;
+      } else {
+        missing.push(name);
+      }
+    }
+  }
+  if (changed) writeFileSync(lockPath, JSON.stringify(lock, null, 2) + "\n");
+  return { promoted, missing };
+}