@wix/agent-skills 1.20.1 → 1.22.0

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

@@ -1,36 +1,59 @@
-// Attach a NEW headless frontend to an EXISTING Wix site — the fast path for a site that already
+// 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
-// fast-path.mjs. Nothing on the site is created, changed or deleted; there is no seed step.
+// 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|static] [--subfolder [--folder-name <name>]]
+//   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): scaffolds the CLI's blank Astro template with the hosting adapter,
-//               ready for `wix build` / `wix release`. react|static: writes wix.config.json into the
-//               folder and stops — the caller scaffolds (Vite / plain HTML) per SKILL.md.
-// The project is created 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.
+// --stack          astro (default) in a folder without a project: copies the first vertical's
+//                  composed template (templates/<vertical>/project). 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 { dirname, join, resolve } from "node:path";
+import { cpSync, existsSync, mkdirSync, openSync, readFileSync, writeFileSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+import { writeAgentsMd } from "./agents-md.mjs";
+import { listVerticals, templatesDir } from "./templates.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";
+// The shipped code: the repository's templates/ (a checkout, the cache, or fetched now, in a second).
+let TEMPLATES;
+try { TEMPLATES = templatesDir(); } catch (e) { fail("templates", e.message); }
 
 const emit = (event, extra = {}) => console.log(JSON.stringify({ event, ...extra }));
 const fail = (step, detail) => {
@@ -44,25 +67,46 @@ const flag = (name) => {
   const i = argv.indexOf(`--${name}`);
   return i !== -1 && argv[i + 1] && !argv[i + 1].startsWith("--") ? argv[i + 1] : null;
 };
-const siteId = flag("site");
-const stack = flag("stack") ?? "astro";
+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");
-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);
+// ---- 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 = listVerticals(TEMPLATES);
 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|static]`);
+  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", "static"].includes(stack)) fail("args", `unknown stack "${stack}" — astro, react or static`);
-if (existsSync(join(process.cwd(), "wix.config.json"))) {
-  fail("args", "the current directory is already a Wix project (wix.config.json) — attach creates a new frontend; run deploy.mjs here instead");
+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) => {
@@ -92,25 +136,27 @@ async function call(base, path, { method = "POST", token, site, body, query } =
 }
 
 const folderName = flag("folder-name") ?? (businessName.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 40) || "site");
-const projectDir = subfolder ? resolve(process.cwd(), folderName) : process.cwd();
+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, instanceId, secrets, hosting = "created";
+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;
-  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) }); }
+  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" } } });
@@ -118,9 +164,23 @@ try {
   } 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 (!appProject) {
+  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;
@@ -146,55 +206,54 @@ try {
   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 = String(appProject.baseUrl).replace(/\/$/, "");
-emit("attached", { siteId, appId, baseUrl, hosting, note: hosting === "reused" ? "this site already has a headless frontend at baseUrl; `wix release` from this project replaces it" : undefined });
+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 -------------------------------------------------------------------------------
+// ---- 2 · scaffold (only where there is no project) -------------------------------------------------
 mkdirSync(projectDir, { recursive: true });
-if (stack === "astro") {
-  // 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 });
+if (stack === "astro" && mode === "scaffold") {
+  // The first vertical's composed template: the CLI's blank scaffold with the vertical deployed
+  // and its lockfile, the same folder `wix create --template-path` copies for a new site. Copied
+  // here because the CLI's create makes a new site and this folder gets an existing one. Further
+  // verticals are deployed below.
+  cpSync(join(templatesDir({ need: `${verticals[0]}/project` }), verticals[0], "project"), projectDir, { recursive: true, force: false, errorOnExist: false });
   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");
@@ -211,15 +270,18 @@ writeFileSync(join(projectDir, ".env.local"), [
   `WIX_CLIENT_SECRET=${quote(secrets.appSecret)}`,
   "",
 ].join("\n"));
-emit("scaffolded", { folder: folderName, stack, template: stack === "astro" ? `${TEMPLATES_REPO}#${TEMPLATE_PATH}` : null });
+emit(mode === "link" ? "linked" : mode === "config-only" ? "configured" : "scaffolded", { folder: folderName, stack, template: mode === "scaffold" && stack === "astro" ? join(TEMPLATES, verticals[0], "project") : 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 (stack !== "astro") {
-  emit("ready", { projectDir, siteId, appId, baseUrl, hosting, 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` });
+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 ---------------------------------------------------
+// ---- 3 · deploy shipped code + deps (adds nothing to a scaffold from the template) --------------
 let deployResult = {};
 {
   const deploy = spawnSync("node", [join(SKILL_ROOT, "install", "deploy.mjs"), ...verticals, "--stack", stack], { cwd: projectDir, encoding: "utf8", timeout: 60_000 });
@@ -229,12 +291,16 @@ let deployResult = {};
   emit("deployed", deployResult);
 }
 
-// ---- 4 · dependency install, detached -----------------------------------------------------------
-const installLog = join(projectDir, "npm-install.log");
-const logFd = openSync(installLog, "a");
-const install = spawn("sh", ["-c", "npm ci --ignore-scripts || npm install --ignore-scripts"], { cwd: projectDir, detached: true, stdio: ["ignore", logFd, logFd] });
-install.unref();
-emit("install_started", { log: installLog, doneMarker: "node_modules/.package-lock.json" });
+// ---- 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", {
@@ -243,11 +309,20 @@ emit("ready_for_brand_layer", {
   appId,
   baseUrl,
   hosting,
+  frontend,
   verticals,
   dashboardUrl: `https://manage.wix.com/dashboard/${siteId}`,
   productsUrl: deployResult.productsUrl,
   categoriesUrl: deployResult.categoriesUrl,
-  install: { log: installLog, doneMarker: "node_modules/.package-lock.json" },
+  mode,
+  stack,
+  install,
   seed: null,
-  next: "the site's content is live already — nothing to seed; read what it holds through the deployed data layer, theme SiteLayout + write the pages; wait for the install marker, build, release",
+  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

@@ -43,21 +43,25 @@ 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";
 
 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,8 +77,6 @@ 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",
   },
@@ -179,7 +181,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(
@@ -362,13 +364,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 +374,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("; ");
   }
 }
 

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 };
+}