@wix/agent-skills 1.20.0 → 1.21.0

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

@@ -0,0 +1,360 @@
+// Attach a NEW headless frontend to an EXISTING Wix site — setup's sibling for a site that already
+// exists (named in the prompt by its id). `init`/`wix create` cannot do this: they always create
+// a site. This script does what they do AFTER creating one — OAuth app, managed hosting, env
+// vars, `wix.config.json` — against the site id given, then scaffolds and deploys like
+// setup.mjs. Nothing on the site is created, changed or deleted; there is no seed step.
+//
+//   node <SKILL_ROOT>/install/attach.mjs [--site <metaSiteId>] --business-name "<Brand>" \
+//        --vertical <a>[,<b>…] [--stack astro|react|lib|static] [--hosting wix|self [--origin <url>[,<url>]]] \
+//        [--subfolder [--folder-name <name>]]
+//
+// --hosting        wix (default): the frontend releases to Wix hosting — the site's app project is
+//                  created or reused and `wix release` uploads to its *.wix-site-host.com address.
+//                  self: the frontend is hosted elsewhere (Vercel, a Flask server, …): no app
+//                  project, no Wix address, no Astro template; the OAuth app, wix.config.json and
+//                  .env.local are still set up, the code deploys for --stack, and the origins given
+//                  in --origin go on the OAuth app's redirect allow-list, which is what a Wix-hosted
+//                  flow (checkout) needs to return to a frontend on another host.
+//
+// --site           the site. May be omitted when the folder holds a wix.config.json: then it is
+//                  the site in that config (what `init` left behind in an empty folder).
+// --business-name  the site's name (names the folder, the hosting slug and the app project).
+// --vertical       which shipped code deploys (no seed runs — the site owns its content). Both are
+//                  the caller's decision, read off the site before calling this (SKILL.md step 3).
+// --stack          astro (default) in a folder without a project: scaffolds the CLI's blank Astro
+//                  template with the hosting adapter. react|static there: writes wix.config.json
+//                  and stops — the caller scaffolds (Vite / plain HTML) per SKILL.md. In a folder
+//                  that holds a project, --stack is required and nothing is scaffolded.
+//
+// The FOLDER decides, on file markers only:
+//   - a project (package.json or index.html) AND wix.config.json → refuses: a Wix project with a
+//     frontend already; deploy.mjs adds a solution to it.
+//   - a project, no config → LINK: the hosting calls, then wix.config.json and .env.local are
+//     written into the project as it is, the shipped code deploys for --stack, the install starts.
+//   - no project (empty, or only a config for this same site) → the scaffold path above.
+//   - a config naming a different site → refuses: never re-point a folder; use --subfolder.
+// The project lives in the CURRENT DIRECTORY — the folder that already holds the installed skills —
+// so it is self-contained. `--subfolder` (opt-in) creates it in a new folder named after the
+// business instead.
+//
+// Emits ONE JSON event per line (attached, scaffolded, deployed, install_started,
+// ready_for_brand_layer, or error). Requires a logged-in Wix CLI (`npx @wix/cli@latest whoami`)
+// whose account owns or co-manages the site.
+import { spawn, spawnSync, execFileSync } from "node:child_process";
+import { cpSync, existsSync, mkdirSync, mkdtempSync, openSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { basename, dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { writeAgentsMd } from "./agents-md.mjs";
+
+const SKILL_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const MANAGE = "https://manage.wix.com";
+const API = "https://www.wixapis.com";
+const HEADLESS_PROJECT_TYPE_ID = "eb363dea-85a0-4159-9b05-949542be5079";
+const TEMPLATES_REPO = "https://github.com/wix/headless-templates.git";
+const TEMPLATE_PATH = "astro/blank";
+
+const emit = (event, extra = {}) => console.log(JSON.stringify({ event, ...extra }));
+const fail = (step, detail) => {
+  emit("error", { step, detail: String(detail).slice(0, 600) });
+  process.exit(1);
+};
+
+// ---- args ---------------------------------------------------------------------------------------
+const argv = process.argv.slice(2);
+const flag = (name) => {
+  const i = argv.indexOf(`--${name}`);
+  return i !== -1 && argv[i + 1] && !argv[i + 1].startsWith("--") ? argv[i + 1] : null;
+};
+const stackFlag = flag("stack");
+const hosting0 = flag("hosting") ?? "wix";
+const origins = (flag("origin") ?? "").split(",").map((o) => o.trim().replace(/\/$/, "")).filter(Boolean);
+const subfolder = argv.includes("--subfolder");
+// ---- the folder ---------------------------------------------------------------------------------
+const cwd = process.cwd();
+const has = (p) => existsSync(join(cwd, p));
+const cwdConfig = has("wix.config.json") ? JSON.parse(readFileSync(join(cwd, "wix.config.json"), "utf8")) : null;
+const hasProject = has("package.json") || has("index.html");
+const siteId = flag("site") ?? cwdConfig?.siteId ?? cwdConfig?.projectId ?? null;
+const stack = stackFlag ?? "astro";
+const knownVerticals = readdirSync(join(SKILL_ROOT, "references"), { withFileTypes: true })
+  .filter((d) => d.isDirectory() && d.name !== "shared" && existsSync(join(SKILL_ROOT, "references", d.name, "app")))
+  .map((d) => d.name);
+const verticals = argv
+  .flatMap((a, i) => (a === "--vertical" && argv[i + 1] ? argv[i + 1].split(",") : []))
+  .map((v) => v.trim())
+  .filter(Boolean);
+const businessName = flag("business-name");
+if (!siteId || !/^[0-9a-f-]{36}$/i.test(siteId) || !businessName || !verticals.length) {
+  fail("args", `usage: attach.mjs [--site <metaSiteId>] --business-name "<Brand>" --vertical <${knownVerticals.join("|")}>[,…] [--stack astro|react|lib|static] (--site may be omitted when wix.config.json is here)`);
+}
+for (const v of verticals) if (!knownVerticals.includes(v)) fail("args", `unknown vertical "${v}" — shipped verticals: ${knownVerticals.join(", ")}`);
+if (!["astro", "react", "lib", "static"].includes(stack)) fail("args", `unknown stack "${stack}" — astro, react, lib or static`);
+if (!["wix", "self"].includes(hosting0)) fail("args", `unknown --hosting "${hosting0}" — wix or self`);
+for (const o of origins) if (!/^https?:\/\/[^/\s]+$/.test(o)) fail("args", `--origin must be a scheme and host such as https://shop.example.com or http://localhost:8000, got "${o}"`);
+if (hosting0 === "self" && stack === "astro" && !hasProject && !stackFlag) {
+  fail("args", "--hosting self scaffolds nothing: pass --stack for the frontend you will host (react|lib|static), or attach from inside the project on disk");
+}
+if (!subfolder) {
+  if (hasProject && cwdConfig) {
+    fail("place", "this folder is already a Wix project with a frontend (wix.config.json and a project): nothing to attach. deploy.mjs <vertical> adds this skill's code or a solution to it; then ONE npm install");
+  }
+  if (cwdConfig && (cwdConfig.siteId ?? cwdConfig.projectId) !== siteId) {
+    fail("place", `this folder is attached to site ${cwdConfig.siteId ?? cwdConfig.projectId}, not ${siteId} — a folder is never re-pointed; attach the other site with --subfolder`);
+  }
+  if (hasProject && !stackFlag) {
+    fail("args", "attaching a project on disk needs --stack astro|react|lib|static — the stack you resolved in SKILL.md step 1 for this project");
+  }
+}
+const mode = !subfolder && hasProject ? "link" : hosting0 === "self" ? "config-only" : "scaffold";
+emit("folder", { mode, stack, hosting: hosting0, project: hasProject, config: cwdConfig ? "same site" : null });
+
+// ---- http ---------------------------------------------------------------------------------------
+const cliToken = (site) => {
+  const r = spawnSync("npx", ["-y", "@wix/cli@latest", "token", ...(site ? ["--site", site] : [])], { encoding: "utf8", timeout: 120_000 });
+  const t = (r.stdout || "").trim();
+  if (r.status !== 0 || !t) fail("auth", (r.stderr || r.stdout || "no token — is the Wix CLI logged in? (npx @wix/cli@latest whoami)").slice(-400));
+  return t;
+};
+async function call(base, path, { method = "POST", token, site, body, query } = {}) {
+  const url = new URL(base + path);
+  for (const [k, v] of Object.entries(query ?? {})) url.searchParams.set(k, String(v));
+  const res = await fetch(url, {
+    method,
+    headers: {
+      Authorization: token,
+      "Content-Type": "application/json",
+      "X-XSRF-TOKEN": "nocheck",
+      Cookie: "XSRF-TOKEN=nocheck",
+      "User-Agent": "wix-cli",
+      ...(site ? { "wix-site-id": site } : {}),
+    },
+    body: body === undefined ? undefined : JSON.stringify(body),
+  });
+  const text = await res.text();
+  if (!res.ok) throw new Error(`${method} ${url.pathname} ${res.status}: ${text.slice(0, 300)}`);
+  try { return JSON.parse(text); } catch { return {}; }
+}
+
+const folderName = flag("folder-name") ?? (businessName.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 40) || "site");
+const projectDir = subfolder ? resolve(cwd, folderName) : cwd;
+if (subfolder && existsSync(join(projectDir, "wix.config.json"))) fail("args", `${folderName}/ is already a Wix project — pick --folder-name, or run deploy.mjs there`);
+
+// ---- 1 · attach: OAuth app + hosting + env, on the manage host with a site token -----------------
+// The same calls `init` makes after it has created a site, in the same order.
+const siteToken = cliToken(siteId);
+const opts = { token: siteToken, site: siteId };
+let appId, appProject = null, instanceId, secrets, hosting = hosting0 === "self" ? "self" : "created";
+try {
+  const comp = await call(MANAGE, "/_api/companion-apps/v1/companion-apps/get-or-create", { ...opts, body: {} });
+  appId = comp.companionApp?.id;
+  if (!appId) throw new Error("get-or-create returned no companion app id");
+  const slug = folderName;
+  if (hosting0 === "wix") {
+    try { appProject = (await call(MANAGE, `/_api/wix-code-app-projects/v1/app-projects/${appId}`, { ...opts, method: "GET" })).appProject; } catch { appProject = null; }
+    if (appProject) {
+      hosting = "reused";
+    } else {
+      try { await call(MANAGE, `/apps-service/v1/apps/${appId}/set-namespace`, { ...opts, method: "PATCH", body: { appId, appName: businessName, namespace: slug } }); }
+      catch (e) { emit("note", { step: "set-namespace", detail: String(e.message).slice(0, 200) }); }
+    }
+  }
+  try {
+    const inst = await call(MANAGE, "/apps-installer-service/v1/app-instance/install", { ...opts, body: { tenant: { id: siteId, tenantType: "SITE" }, appInstance: { appDefId: appId, version: "latest" } } });
+    instanceId = inst.appInstance?.id;
+  } catch (e) { emit("note", { step: "install", detail: String(e.message).slice(0, 200) }); }
+  secrets = (await call(MANAGE, `/apps-service/v1/apps/${appId}`, { ...opts, method: "GET", query: { withSecrets: true } })).app?.appSecrets;
+  if (!secrets?.appSecret) throw new Error("app secrets unavailable for this app");
+  if (hosting0 === "self") {
+    // No Wix hosting. The one thing a frontend on another host needs from the site: its origins on
+    // the OAuth app's redirect allow-list, so checkout and the other Wix-hosted flows can return.
+    // The public OAuth Apps API (wix-manage: Manage OAuth Apps), merged with what is already there.
+    if (origins.length) {
+      const current = (await call(API, `/oauth-app/v1/oauth-apps/${appId}`, { ...opts, method: "GET" })).oAuthApp ?? {};
+      const merged = [...new Set([...(current.allowedRedirectDomains ?? []), ...origins])];
+      await call(API, `/oauth-app/v1/oauth-apps/${appId}`, { ...opts, method: "PATCH", body: { oAuthApp: { allowedRedirectDomains: merged }, mask: { paths: ["allowedRedirectDomains"] } } });
+      emit("origins_allowed", { appId, allowedRedirectDomains: merged });
+    } else {
+      emit("note", { step: "origins", detail: "no --origin given: add the frontend's origins to the OAuth app's allowedRedirectDomains (wix-manage: Manage OAuth Apps) before the first checkout test" });
+    }
+  }
+  if (hosting0 === "wix" && !appProject) {
+    appProject = (await call(MANAGE, "/_api/wix-code-app-projects/v1/app-projects", { ...opts, body: { appProject: { id: appId, displayName: businessName.slice(0, 50), slug, appProjectTypeId: HEADLESS_PROJECT_TYPE_ID } } })).appProject;
+  }
+  if (hosting0 === "wix") {
+  if (!appProject?.baseUrl) throw new Error("app project has no baseUrl");
+  const prod = String(appProject.baseUrl).replace(/\/$/, "");
+  const host = new URL(appProject.baseUrl).hostname;
+  const local = "http://localhost:4321";
+  await call(MANAGE, `/oauth-app-service/v1/oauth-apps/${appId}`, { ...opts, method: "PATCH", body: {
+    oAuthApp: {
+      id: appId,
+      allowedDomains: [local, `https://(.*)-${host}`, prod],
+      allowedRedirectUris: [`${local}/api/auth/callback`, `${local}/api/auth/logout-callback`, `https://*-${host}/api/auth/callback`, `https://*-${host}/api/auth/logout-callback`, `${prod}/api/auth/callback`, `${prod}/api/auth/logout-callback`],
+      redirectUrlWixPages: prod,
+      origin: "other",
+    },
+    mask: { paths: ["allowedDomains", "allowedRedirectUris", "redirectUrlWixPages", "origin"] },
+  } });
+  if (!instanceId) {
+    // reused app: the instance id is on the existing env, keep it
+    try {
+      const env = await call(MANAGE, `/_api/wix-code-app-environments/v2/app-projects/${appProject.id}/app-environment-variables`, { ...opts, method: "GET", query: { environment: "system_global" } });
+      instanceId = (env.appEnvironmentVariables ?? []).find((v) => v.key === "WIX_CLIENT_INSTANCE_ID")?.value ?? null;
+    } catch { /* fall through */ }
+  }
+  const variables = { WIX_CLIENT_ID: appId, WIX_CLIENT_SECRET: secrets.appSecret, WIX_CLIENT_PUBLIC_KEY: secrets.webhookPublicKey, ...(instanceId ? { WIX_CLIENT_INSTANCE_ID: instanceId } : {}) };
+  await call(MANAGE, `/_api/wix-code-app-environments/v2/bulk/app-projects/${appProject.id}/app-environment-variables/upsert`, { ...opts, body: {
+    appProjectId: appProject.id, environment: "system_global", mutability: "STATIC", returnEntity: true, returnAllEnvironment: true, variables,
+  } });
+  }
+} catch (e) {
+  fail("attach", e?.message || e);
+}
+const baseUrl = appProject ? String(appProject.baseUrl).replace(/\/$/, "") : null;
+// Is a frontend serving at that address? The hosting project says nothing about it (init and the
+// provisioning call create one with nothing behind it). The site's release slots do: the release
+// with slug `prod` is production traffic and names the deployment it serves — the same read the
+// headless back office makes for its frontend status. Absent means nothing was ever released.
+// Deployments keep their own addresses, so a replaced one is not lost; prod can be pointed back.
+// A folder that reaches this point is not the one that released (a linked project never runs
+// attach), so a `prod` release here means a NEW project is about to take over a live frontend.
+let frontend = null;
+if (appProject) {
+  try {
+    const r = await call(MANAGE, `/_api/wix-code-app-releases/v1/app-projects/${appProject.id}/app-releases/query`, { ...opts, body: { query: { cursorPaging: { limit: 20 } } } });
+    const prod = (r.appReleases ?? []).find((x) => x.releaseSlug === "prod");
+    frontend = prod
+      ? { serving: true, releasedAt: prod.updatedDate ?? prod.createdDate ?? null, deploymentId: prod.appDeploymentId ?? null }
+      : { serving: false };
+  } catch (e) {
+    emit("note", { step: "releases", detail: String(e.message).slice(0, 200) });
+    frontend = { serving: null };
+  }
+}
+const note =
+  hosting === "self" ? "no Wix hosting: the frontend is yours to host; its origins must be on the OAuth app's allow-list"
+  : frontend?.serving === true
+    ? `a frontend is SERVING at ${baseUrl}, released ${frontend.releasedAt}. This is a new project: a \`wix release\` from here replaces it (the current deployment keeps its own address and prod can be pointed back). Tell the user before releasing; unless the brief asked for a new frontend, ask.`
+  : frontend?.serving === false
+    ? `${hosting === "created" ? "hosting created" : "hosting exists"} at ${baseUrl}; nothing served yet — the first release from this project fills it`
+  : frontend
+    ? `could not read whether a frontend is serving at ${baseUrl}; check the address before releasing`
+    : undefined;
+emit("attached", { siteId, appId, baseUrl, hosting, frontend, origins: hosting0 === "self" ? origins : undefined, note });
+
+// ---- 2 · scaffold (only where there is no project) -------------------------------------------------
+mkdirSync(projectDir, { recursive: true });
+if (stack === "astro" && mode === "scaffold") {
+  // The CLI's own blank template (what `wix create` copies), then what its extender adds: the
+  // hosting adapter, React islands, the `wix` scripts. Pinned like a freshly created project.
+  const tmp = mkdtempSync(join(tmpdir(), "wix-template-"));
+  const clone = spawnSync("git", ["clone", "--quiet", "--depth", "1", "--filter=blob:none", "--sparse", TEMPLATES_REPO, tmp], { encoding: "utf8", timeout: 120_000 });
+  if (clone.status !== 0) fail("scaffold", clone.stderr || "git clone of the template repo failed");
+  const sparse = spawnSync("git", ["-C", tmp, "sparse-checkout", "set", TEMPLATE_PATH], { encoding: "utf8", timeout: 60_000 });
+  if (sparse.status !== 0 || !existsSync(join(tmp, TEMPLATE_PATH, "package.json"))) fail("scaffold", sparse.stderr || `template ${TEMPLATE_PATH} not found in ${TEMPLATES_REPO}`);
+  cpSync(join(tmp, TEMPLATE_PATH), projectDir, { recursive: true, force: false, errorOnExist: false });
+  rmSync(tmp, { recursive: true, force: true });
+  const pkgPath = join(projectDir, "package.json");
+  const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+  pkg.name = folderName;
+  pkg.scripts = { astro: "astro", dev: "wix dev", build: "wix build", wix: "wix", preview: "wix preview", release: "wix release", generate: "wix generate", env: "wix env", skills: "wix skills" };
+  pkg.devDependencies = {
+    ...(pkg.devDependencies ?? {}),
+    "@astrojs/react": "^4.3.0",
+    "@types/react": "^18.3.1",
+    "@types/react-dom": "^18.3.1",
+    "@wix/cli": "^1.1.92",
+    "@wix/astro-wix-hosting-adapter": "^2.0.0",
+    react: "18.3.1",
+    "react-dom": "18.3.1",
+  };
+  writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + "\n");
+  writeFileSync(join(projectDir, "astro.config.mjs"), `// @ts-check
+import { defineConfig } from "astro/config";
+import wix from "@wix/astro";
+import wixPages from "@wix/astro-pages";
+import react from "@astrojs/react";
+import wixHostingAdapter from "@wix/astro-wix-hosting-adapter";
+
+// https://astro.build/config
+export default defineConfig({
+  integrations: [wix(), wixPages(), react()],
+  security: { checkOrigin: false },
+  adapter: wixHostingAdapter(),
+  image: { domains: ["static.wixstatic.com"] },
+  output: "server",
+});
+`);
+  const gi = join(projectDir, ".gitignore");
+  const cur = existsSync(gi) ? readFileSync(gi, "utf8") : "";
+  if (!/\.env/.test(cur)) writeFileSync(gi, cur + "\n# local env (pulled from Wix)\n.env.local\n.env\n");
+}
+writeFileSync(join(projectDir, "wix.config.json"), JSON.stringify({ appId, siteId }, null, 2) + "\n");
+// The env the CLI's build reads. Same content `wix env pull` writes; written here so the build
+// needs no extra call.
+const quote = (v) => `"${String(v ?? "").replace(/"/g, '\\"')}"`;
+writeFileSync(join(projectDir, ".env.local"), [
+  `WIX_CLOUD_PROVIDER=${quote("wix")}`,
+  `WIX_CLIENT_ID=${quote(appId)}`,
+  ...(instanceId ? [`WIX_CLIENT_INSTANCE_ID=${quote(instanceId)}`] : []),
+  `WIX_CLIENT_PUBLIC_KEY=${quote(secrets.webhookPublicKey)}`,
+  `WIX_CLIENT_SECRET=${quote(secrets.appSecret)}`,
+  "",
+].join("\n"));
+emit(mode === "link" ? "linked" : mode === "config-only" ? "configured" : "scaffolded", { folder: folderName, stack, template: mode === "scaffold" && stack === "astro" ? `${TEMPLATES_REPO}#${TEMPLATE_PATH}` : null });
+// the agent config files `wix create` writes (attach never runs the CLI's scaffold at all); fill-only
+emit("agent_configs", writeAgentsMd(projectDir, { skill: basename(SKILL_ROOT), stack }));
+
+if (mode !== "link" && (stack !== "astro" || mode === "config-only")) {
+  emit("ready", { projectDir, siteId, appId, baseUrl, hosting, frontend, stack, dashboardUrl: `https://manage.wix.com/dashboard/${siteId}`,
+    next: `scaffold the ${stack} project in this folder per SKILL.md, then deploy.mjs <vertical…> --stack ${stack} (the client id is read from wix.config.json); no seed — the site owns its content` +
+      (hosting === "self" ? `; you host it: origins on the OAuth app allow-list now: ${origins.join(", ") || "none — add them before the first checkout test"}` : "") });
+  process.exit(0);
+}
+
+// ---- 3 · deploy shipped code + deps + lockfile ---------------------------------------------------
+let deployResult = {};
+{
+  const deploy = spawnSync("node", [join(SKILL_ROOT, "install", "deploy.mjs"), ...verticals, "--stack", stack], { cwd: projectDir, encoding: "utf8", timeout: 60_000 });
+  if (deploy.status !== 0) fail("deploy", deploy.stderr || deploy.stdout);
+  try { deployResult = JSON.parse(deploy.stdout); } catch { /* keep going */ }
+  if (deployResult.error) fail("deploy", deployResult.error);
+  emit("deployed", deployResult);
+}
+
+// ---- 4 · dependency install, detached (any project with a package.json) --------------------------
+let install = null;
+if (existsSync(join(projectDir, "package.json"))) {
+  const installLog = join(projectDir, "npm-install.log");
+  const logFd = openSync(installLog, "a");
+  const child = spawn("sh", ["-c", existsSync(join(projectDir, "package-lock.json")) ? "npm ci --ignore-scripts || npm install --ignore-scripts" : "npm install --ignore-scripts"], { cwd: projectDir, detached: true, stdio: ["ignore", logFd, logFd] });
+  child.unref();
+  install = { log: installLog, doneMarker: "node_modules/.package-lock.json" };
+  emit("install_started", install);
+}
+
+// ---- done ----------------------------------------------------------------------------------------
+emit("ready_for_brand_layer", {
+  projectDir,
+  siteId,
+  appId,
+  baseUrl,
+  hosting,
+  frontend,
+  verticals,
+  dashboardUrl: `https://manage.wix.com/dashboard/${siteId}`,
+  productsUrl: deployResult.productsUrl,
+  categoriesUrl: deployResult.categoriesUrl,
+  mode,
+  stack,
+  install,
+  seed: null,
+  next:
+    "the site's content is live already — nothing to seed; get the measure of the site (SKILL.md step 3), theme + write the pages" +
+    (mode === "link" && hosting !== "self" ? "; make the project what its stack needs on Wix hosting (SKILL.md step 1)" : "") +
+    (install ? "; wait for the install marker" : "") +
+    (hosting === "self"
+      ? `; you host it — no wix release; origins on the OAuth app allow-list now: ${origins.join(", ") || "none — add them before the first checkout test"}; add the public one when it goes live`
+      : "; then release as step 5 says for the stack"),
+});

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

@@ -8,6 +8,21 @@
 //   --stack react  — copies only the core (app/) into src/, and writes the public OAuth
 //                  client id into src/wix/config.ts (pass --client-id, or it's read from
 //                  wix.config.json's appId when present).
+//   --stack lib    — a bundled JS project that isn't React (Vue, Svelte, Solid, plain Vite): copies
+//                  ONLY the data layer — shared app/wix/ (sdk, media, money, config) and each
+//                  vertical's app/wix/<vertical>/ (data layer, cart store, types, *-core rules) —
+//                  none of which imports React; writes the client id like react. No hooks, no
+//                  components, no global.css, no Tailwind deps. The agent writes its framework's
+//                  stores and components against the same DTO contracts.
+//   --stack static — a site with NO bundler (plain HTML/CSS/JS): composes the REST layer flat into
+//                  <out>/js/wix/ — shared/rest/ (client, media, config) + each vertical's rest/ + the
+//                  vertical's transport-agnostic core files (types, *-core) from its app/ — writes
+//                  the client id, and strips it to browser-ready ESM with tsc (comments kept, the
+//                  .ts sources kept beside the .js). No package.json is touched. Storefront only
+//                  until other verticals ship a rest/. `--out <dir>` (default: the project root)
+//                  is the folder the site is served from — the one wix.config.json's
+//                  site.outputDirectory points at — so the modules land where the pages import
+//                  them and nothing else in the project gets uploaded.
 //
 // TWO mechanisms, driven by the same vertical arguments:
 // 1. Recursive file copy with force:false — only files that AREN'T there yet are written, so
@@ -158,17 +173,18 @@ const flag = (name) => {
 const stack = flag("stack") ?? "astro";
 const clientIdFlag = flag("client-id");
 const planPath = flag("plan");
+const outDir = flag("out");
 const flagArgs = new Set(
-  ["--stack", "--client-id", "--plan", stack, clientIdFlag, planPath].filter(Boolean),
+  ["--stack", "--client-id", "--plan", "--out", stack, clientIdFlag, planPath, outDir].filter(Boolean),
 );
 const requested = [...new Set(argv.filter((a) => !flagArgs.has(a)))];
 
 const result = { stack, verticals: [], skillRoot: SKILL_ROOT };
 
-if (!["astro", "react"].includes(stack)) {
+if (!["astro", "react", "lib", "static"].includes(stack)) {
   console.log(
     JSON.stringify({
-      error: `unknown --stack "${stack}" — expected astro|react`,
+      error: `unknown --stack "${stack}" — expected astro|react|lib|static`,
     }),
   );
   process.exit(1);
@@ -193,6 +209,87 @@ if (!Array.isArray(uploadPolicies)) {
   console.log(JSON.stringify({ error: "plan.capabilities.mediaUpload.policies must be an array" }));
   process.exit(1);
 }
+// ---- static stack: the REST layer, composed flat and stripped ------------------------------------
+if (stack === "static") {
+  const { spawnSync } = await import("node:child_process");
+  const { rmSync } = await import("node:fs");
+  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;
+  }
+  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);
+  }
+  const missing = requested.filter((v) => !existsSync(join(REF, v, "rest")));
+  if (missing.length) {
+    console.log(JSON.stringify({ error: `no rest/ layer yet for ${missing.map((v) => `"${v}"`).join(", ")} — the static stack ships: ${VERTICALS.filter((v) => existsSync(join(REF, v, "rest"))).join(", ")}` }));
+    process.exit(1);
+  }
+  // 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);
+    // 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);
+    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"));
+    for (const f of own) {
+      const fp = join(JS, f);
+      if (!existsSync(fp)) continue;
+      const src = readFileSync(fp, "utf8");
+      const fixed = src.replace(/from\s+"\.\/types(?:\.js)?"/g, `from "./${vertical}-types.js"`);
+      if (fixed !== src) writeFileSync(fp, fixed);
+    }
+    result.verticals.push(vertical);
+  }
+  // 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.
+  for (const f of readdirSync(JS).filter((f) => f.endsWith(".ts"))) {
+    const src = readFileSync(join(JS, f), "utf8");
+    const fixed = src.replace(/(from\s+"\.\/[^"]+?)(?<!\.js)"/g, '$1.js"');
+    if (fixed !== src) writeFileSync(join(JS, f), fixed);
+  }
+  const cfg = join(JS, "config.ts");
+  const current = readFileSync(cfg, "utf8");
+  if (/WIX_CLIENT_ID: string = ""/.test(current)) {
+    writeFileSync(cfg, current.replace(/WIX_CLIENT_ID: string = ""/, `WIX_CLIENT_ID: string = "${clientId}"`));
+    result.clientId = "written";
+  } else {
+    result.clientId = "already_set";
+  }
+  // Strip to ESM with tsc — comments are the spec for whoever reads js/wix/, so they stay.
+  const sources = readdirSync(JS).filter((f) => f.endsWith(".ts")).map((f) => join(JS, f));
+  const tsc = spawnSync(
+    "npx",
+    ["-y", "-p", "typescript@5", "tsc", ...sources, "--outDir", JS, "--module", "esnext", "--target", "es2022",
+     "--moduleResolution", "bundler", "--lib", "es2022,dom", "--strict", "--skipLibCheck", "--removeComments", "false"],
+    { encoding: "utf8", timeout: 180_000 },
+  );
+  if (tsc.status !== 0) {
+    console.log(JSON.stringify({ ...result, error: `tsc strip failed: ${(tsc.stdout || tsc.stderr || "").slice(-800)}` }));
+    process.exit(1);
+  }
+  rmSync(join(JS, "tsconfig.json"), { force: true });
+  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}`);
+  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);
+}
+
 if (uploadPolicies.length && stack !== "astro") {
   console.log(JSON.stringify({ error: "mediaUpload currently requires --stack astro because it ships a validated server endpoint" }));
   process.exit(1);
@@ -212,8 +309,9 @@ for (const policy of uploadPolicies) {
 }
 
 // ---- copy ---------------------------------------------------------------------------------------
-// Shared core — always.
-cpSync(join(REF, "shared", "app"), SRC, COPY);
+// Shared core — always. The lib stack takes only the framework-free wix/ part (no styles).
+if (stack === "lib") cpSync(join(REF, "shared", "app", "wix"), join(SRC, "wix"), COPY);
+else cpSync(join(REF, "shared", "app"), SRC, COPY);
 
 if (uploadPolicies.length) {
   cpSync(join(REF, "shared", "capabilities", "media-upload", "app"), SRC, COPY);
@@ -221,10 +319,12 @@ if (uploadPolicies.length) {
 }
 
 const unknown = requested.filter((v) => !VERTICALS.includes(v));
-const wantedDeps = { ...SHARED_DEPS };
+// 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"]);
 for (const vertical of requested.filter((v) => VERTICALS.includes(v))) {
-  cpSync(join(REF, vertical, "app"), SRC, COPY);
+  if (stack === "lib") cpSync(join(REF, vertical, "app", "wix"), join(SRC, "wix"), COPY);
+  else cpSync(join(REF, vertical, "app"), SRC, COPY);
   if (stack === "astro" && existsSync(join(REF, vertical, "app-astro"))) {
     cpSync(join(REF, vertical, "app-astro"), SRC, COPY);
   }
@@ -386,7 +486,7 @@ if (!clientId && existsSync(join(PROJECT, "wix.config.json"))) {
     JSON.parse(readFileSync(join(PROJECT, "wix.config.json"), "utf8")).appId ??
     null;
 }
-if (stack === "react") {
+if (stack === "react" || stack === "lib") {
   if (clientId) {
     const current = readFileSync(CONFIG_TS, "utf8");
     // A non-null id already set wins; only fill the shipped null placeholder.
@@ -404,7 +504,7 @@ if (stack === "react") {
     }
   } else {
     result.clientId =
-      "missing — pass --client-id (react stack needs the public OAuth client id)";
+      `missing — pass --client-id (the ${stack} stack needs the public OAuth client id)`;
   }
 }
 if (requested.includes("members")) {