@wix/agent-skills 1.31.0 → 1.31.2

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

@@ -16,9 +16,9 @@
 // `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 { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
+import { failure, npmSync } from "./proc.mjs";
 const PINS = JSON.parse(readFileSync(new URL("./pins.json", import.meta.url), "utf8"));
 const WIX_CLI = `@wix/cli@${PINS["@wix/cli"]}`;
 
@@ -60,7 +60,7 @@ export function readWixConfig(cwd) {
 }
 
 const ENV_PULL = ["-y", WIX_CLI, "env", "pull"];
-const runPull = (dir) => spawnSync("npx", ENV_PULL, { cwd: dir, env: { ...process.env, CI: "1" }, encoding: "utf8", timeout: 180_000 });
+const runPull = (dir) => npmSync("npx", ENV_PULL, { cwd: dir, env: { ...process.env, CI: "1" }, encoding: "utf8", timeout: 180_000 });
 
 /**
  * `wix env pull` into `cwd/.env.local`, in place. Every project shape gets the command since Wix CLI
@@ -72,13 +72,15 @@ export function pullEnv(cwd) {
   const envFile = join(cwd, ".env.local");
   const r = runPull(cwd);
   if (r.status === 0 && existsSync(envFile)) return { ok: true, via: "in place" };
-  return { ok: false, error: (r.stderr || r.stdout || `env pull produced no .env.local — is the Wix CLI logged in? (npx ${WIX_CLI} whoami)`).trim().slice(-400) };
+  return { ok: false, error: failure(r, `env pull produced no .env.local — is the Wix CLI logged in? (npx ${WIX_CLI} whoami)`).trim().slice(-400) };
 }
 
 /**
  * Whether a frontend exists in this folder: a `package.json` (a bundled project), an `index.html` at
  * the root (plain pages), or an `index.html` inside the folder the config's `site.outputDirectory`
- * names (a static site laid out for release, pages under site/). Nothing else counts — not this
+ * names (a static site laid out for release, pages under site/). `publicIndex` and `astroPages` tell
+ * a dropped site on its Wix Dev Machine apart from an Astro project: the machine copies the drop's
+ * pages into public/ of an Astro starter that has no src/pages/. Nothing else counts — not this
  * skill's code, not the skills folder, not AGENTS.md: those say who ran here, not what is here.
  */
 export function frontendPresent(cwd = process.cwd()) {
@@ -89,13 +91,50 @@ export function frontendPresent(cwd = process.cwd()) {
     rootIndex: has("index.html"),
     outputIndex: !!outDir && outDir !== "." && has(join(outDir, "index.html")),
     outputDirectory: outDir || null,
+    publicIndex: has(join("public", "index.html")),
+    astroPages: has(join("src", "pages")),
   };
 }
 
 /**
- * What the folder IS, from five file facts — the one classification every script and SKILL.md
+ * The Wix CLI's blank Astro starter (`wix-astro-blank`, templates/blank/project), still as the CLI
+ * left it: every package it declares is one of the blank template's. That is the one frontend the
+ * kit knows carries no work of its own — a Dev Machine's never-released site, a bare `wix create`
+ * — so a vertical's composed template can take its place (deploy.mjs). A starter with any package
+ * of its own is someone's project. The blank template's package.json is read when the templates
+ * are on disk; otherwise the starter's known package names stand in.
+ */
+const BLANK_STARTER = {
+  name: "wix-astro-blank",
+  packages: ["@astrojs/react", "@types/react", "@types/react-dom", "@wix/astro", "@wix/astro-pages", "@wix/astro-wix-hosting-adapter", "@wix/cli", "@wix/dashboard", "@wix/essentials", "@wix/sdk", "astro", "react", "react-dom", "typescript"],
+};
+export function blankStarter(cwd = process.cwd(), blankPkgPath = null) {
+  const pkgPath = join(cwd, "package.json");
+  if (!existsSync(pkgPath)) return false;
+  let pkg;
+  try { pkg = JSON.parse(readFileSync(pkgPath, "utf8")); } catch { return false; }
+  if (pkg.name !== BLANK_STARTER.name) return false;
+  let known = BLANK_STARTER.packages;
+  if (blankPkgPath && existsSync(blankPkgPath)) {
+    try {
+      const blank = JSON.parse(readFileSync(blankPkgPath, "utf8"));
+      known = Object.keys({ ...blank.dependencies, ...blank.devDependencies });
+    } catch { /* the known names stand in */ }
+  }
+  return Object.keys({ ...pkg.dependencies, ...pkg.devDependencies }).every((name) => known.includes(name));
+}
+
+/**
+ * What the folder IS, from a few file facts — the one classification every script and SKILL.md
  * step 3 share: wix.config.json, its site.outputDirectory, the migration variables in .env.local,
- * package.json, index.html. `migrationActive` comes from siteContext (it needs `.env.local`).
+ * package.json, index.html (at the root or in public/), src/pages/. `migrationActive` comes from
+ * siteContext (it needs `.env.local`).
+ *
+ * Two axes decide it: whether a site is bound to the folder (the config), and what frontend is
+ * here (`facts.frontend`: none, the CLI's untouched blank starter, the starter with plain pages in
+ * public/, plain pages with no bundler, or someone's project). The migration flag is read first.
+ * Anything the rows below do not name is `wix-project`, the fill-only path: never scaffold, init,
+ * reseed or delete.
  *
  *   empty             nothing that reads as a project → setup CREATE: the run makes the site, seeds the plan
  *   project           a frontend, no wix.config.json → setup ADOPT: `init` gives it a new, empty site, seeds the plan
@@ -103,6 +142,12 @@ export function frontendPresent(cwd = process.cwd()) {
  *   migration         a config whose .env.local declares an ACTIVE editor migration, with or without the blank
  *                     Astro starter the download carries → setup MIGRATE; nothing seeded. Decided before the
  *                     frontend test: the starter's package.json must not read as a project to iterate on
+ *   static-in-astro   a config, a package.json, public/index.html and no src/pages/ (a site published
+ *                     through the drop flow, on its Wix Dev Machine) → the pages stay plain files in
+ *                     public/; the static REST layer deploys beside them; build and release
+ *   blank-starter     a config and the CLI's blank starter with no work of its own (a Dev Machine's
+ *                     never-released site, a bare `wix create`) → attach.mjs on the config's site: the
+ *                     vertical's composed template takes the starter's place, install and seed run detached
  *   wix-project       a config AND a frontend (package.json, or index.html in the output folder) → iterate:
  *                     never scaffold, init or reseed; deploy.mjs adds a solution, edits, release
  *   published-static  a config, index.html at the ROOT, no package.json, no laid-out output folder (a site
@@ -112,21 +157,30 @@ export function frontendPresent(cwd = process.cwd()) {
 export function folderShape(cwd = process.cwd(), { migrationActive = false } = {}) {
   const config = existsSync(join(cwd, "wix.config.json"));
   const f = frontendPresent(cwd);
+  const starter = f.packageJson && blankStarter(cwd);
   const next = {
     empty: "setup.mjs --vertical <v> --business-name <brand> [--plan]: creates the site here and seeds the plan (CREATE)",
     project: "setup.mjs --vertical <v> --stack <stack> [--plan]: init links the folder to a new, empty site, seeds the plan and deploys (ADOPT)",
     "config-only": "attach.mjs: the site exists and has no frontend yet; read what it holds (the vertical's read-site.mjs) — nothing is seeded; the vertical's seed module with a plan only when the brief supplies or describes content",
     migration: "setup.mjs (MIGRATE): the shipped code into the starter the download carries (or the composed template around a bare config); the site being migrated owns its content — guides/migration.md",
-    "wix-project": "iterate: never scaffold, init or reseed. deploy.mjs <vertical…> --stack <stack> adds a solution, then ONE npm install; file edits for a change; release. Read the site (read-site.mjs) before any seed module runs",
+    "static-in-astro": "a dropped site on its Dev Machine: the pages are plain files in public/, served as they are. deploy.mjs <vertical…> --stack static --out public puts the REST layer in public/js/wix/; wire the pages in place with <script type=\"module\">: do the least that makes them work: connect each control the pages show and add only what a control can't work without (more only when the brief asks), and no Astro pages. Read the site (read-site.mjs); run the vertical's seed module with a plan only for content the brief supplies or describes. Release with npx @wix/cli@latest build && npx @wix/cli@latest release; the URL stays",
+    "blank-starter": "attach.mjs --business-name <brand> --vertical <v…> [--plan plan.json] (the site comes from wix.config.json): the CLI's blank starter with no work of its own, as a Dev Machine or a bare wix create leaves it. attach deploys the vertical onto it with its composed lock and starts the install and the seed detached: build the brand layer while they run, then sync on .install-exit and .seed-exit before release (SKILL.md step 3). Read the site first (read-site.mjs) when it may already hold content",
+    "wix-project": "iterate: never scaffold, init or reseed. deploy.mjs <vertical…> --stack <stack> adds a solution, then one install: node <SKILL_ROOT>/install/install.mjs (it skips when node_modules already satisfies the lock); file edits for a change; release. Read the site (read-site.mjs) before any seed module runs",
     "published-static": "setup.mjs --vertical <v>: the config's site, no init; site/ becomes the upload and the REST layer lands in site/js/wix/; move the pages, styles and assets into site/. Nothing is seeded: read the site, then run the vertical's seed module with a plan when the brief gives content; release keeps the URL",
   };
   let shape;
   if (!config) shape = f.packageJson || f.rootIndex ? "project" : "empty";
   else if (migrationActive) shape = "migration";
+  else if (f.packageJson && f.publicIndex && !f.astroPages) shape = "static-in-astro";
+  else if (starter) shape = "blank-starter";
   else if (f.packageJson || f.outputIndex) shape = "wix-project";
   else if (f.rootIndex) shape = "published-static";
   else shape = "config-only";
-  return { shape, next: next[shape], facts: { config, ...f } };
+  const frontend = !(f.packageJson || f.rootIndex || f.outputIndex) ? "none"
+    : starter ? (f.publicIndex && !f.astroPages ? "starter+static" : "starter")
+    : f.packageJson ? "project"
+    : "static";
+  return { shape, next: next[shape], facts: { config, frontend, starter, ...f } };
 }
 
 /**

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

@@ -18,8 +18,8 @@
 //                  <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)
+//                  .ts sources kept beside the .js). No package.json is touched. Every vertical
+//                  with a rest/ folder is supported. `--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.
@@ -45,7 +45,7 @@ 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";
+import { blankStarter, siteContext } from "./context.mjs";
 const PINS = JSON.parse(readFileSync(new URL("./pins.json", import.meta.url), "utf8"));
 const WIX_CLI = `@wix/cli@${PINS["@wix/cli"]}`;
 
@@ -130,7 +130,7 @@ const VERTICAL_DEPS = {
   blog: {
     core: {
       "@wix/blog": "^1.0.645",
-      "@wix/ricos": "^11.12.0",
+      "@wix/ricos": "^11.17.0", // the viewer-only entry @wix/ricos/viewer
     },
     astro: {
       "@wix/seo": "^1.0.79",
@@ -268,7 +268,7 @@ const siteSearchConfigSource = () =>
   `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");
+  const { npmSync } = await import("./proc.mjs");
   const { rmSync } = await import("node:fs");
   const OUT = outDir ? resolve(PROJECT, outDir) : PROJECT;
   const JS = join(OUT, "js", "wix");
@@ -309,7 +309,11 @@ if (stack === "static") {
       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"`);
+      // The rest/ files import their real paths in the templates (../../shared/rest/client.js,
+      // ../app/wix/<vertical>/cart-core.js); flat in one folder, every import is a sibling.
+      const fixed = src
+        .replace(/from\s+"\.{1,2}\/(?:[^"]*\/)([^"/]+)"/g, 'from "./$1"')
+        .replace(/from\s+"\.\/types(?:\.js)?"/g, `from "./${vertical}-types.js"`);
       if (fixed !== src) writeFileSync(fp, fixed);
     }
     if (VERTICALS.includes(vertical)) result.verticals.push(vertical);
@@ -336,14 +340,14 @@ if (stack === "static") {
   }
   // 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(
+  const tsc = npmSync(
     "npx",
     ["-y", "-p", `typescript@${PINS.typescript}`, "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)}` }));
+    console.log(JSON.stringify({ ...result, error: `tsc strip failed: ${(tsc.stdout || tsc.stderr || tsc.error?.message || `exit ${tsc.status}`).slice(-800)}` }));
     process.exit(1);
   }
   rmSync(join(JS, "tsconfig.json"), { force: true });
@@ -431,7 +435,28 @@ if (siteSearch) {
   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("; ");
+    result.note = [result.note, `siteSearch.install: run node ${join(REF, "shared", "capabilities", "site-search", "seed", "install.mjs")} from the project root after the seed (results appear about half a minute later)`].filter(Boolean).join("; ");
+  }
+}
+
+// ---- the blank starter takes the vertical's composed template --------------------------------
+// A project that is still the blank starter (context.mjs blankStarter: a Dev Machine's, or a bare
+// `wix create`) holds only the blank template's packages. Deploying one vertical onto it makes
+// exactly that vertical's composed template (templates/<vertical>/project: the blank scaffold plus
+// the vertical), so the starter takes the composed package.json dependencies and lockfile, and the
+// install reads the lock instead of resolving the vertical's tree. A project with any package of its
+// own, a second vertical, or two verticals in one run is left alone.
+if (stack === "astro" && result.verticals.length === 1 && blankStarter(PROJECT, join(REF, "blank", "project", "package.json"))) {
+  // The composed project/ is left out of a committed templates copy; templatesDir fetches it on need.
+  const composed = join(templatesDir({ need: `${result.verticals[0]}/project` }), result.verticals[0], "project");
+  if (existsSync(join(composed, "package-lock.json"))) {
+    const pkg = JSON.parse(readFileSync(PKG_JSON, "utf8"));
+    const template = JSON.parse(readFileSync(join(composed, "package.json"), "utf8"));
+    pkg.dependencies = template.dependencies;
+    pkg.devDependencies = template.devDependencies;
+    writeFileSync(PKG_JSON, JSON.stringify(pkg, null, 2) + "\n");
+    cpSync(join(composed, "package-lock.json"), join(PROJECT, "package-lock.json"));
+    result.lockFromTemplate = result.verticals[0];
   }
 }
 
@@ -468,9 +493,9 @@ 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("; ");
+    result.note = [result.note, "install with node <SKILL_ROOT>/install/install.mjs (nothing when node_modules already satisfies the lock)"].filter(Boolean).join("; ");
   } else if (result.depsAdded?.length) {
-    result.note = [result.note, "run `npm install --ignore-scripts` to pick up depsAdded"].filter(Boolean).join("; ");
+    result.note = [result.note, "run node <SKILL_ROOT>/install/install.mjs to pick up depsAdded"].filter(Boolean).join("; ");
   }
 }
 

package/skills/wix-headless-kit/install/env-ignore.mjs

@@ -0,0 +1,16 @@
+// .env.local holds the app's WIX_CLIENT_SECRET (written by `wix env pull`, `init` and attach.mjs), so
+// every project setup.mjs and attach.mjs leave behind ignores it in git. A line `.env` alone does not
+// cover `.env.local`; `.env.local`, `.env*`, `.env.*` or `*.local` do.
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+const COVERS_ENV_LOCAL = /^\s*(\.env\.local|\.env\*|\.env\.\*|\*\.local)\s*$/m;
+
+/** Appends `.env.local` and `.env` to dir/.gitignore unless it already ignores `.env.local`. */
+export function ignoreEnvLocal(dir) {
+  const gi = join(dir, ".gitignore");
+  const cur = existsSync(gi) ? readFileSync(gi, "utf8") : "";
+  if (COVERS_ENV_LOCAL.test(cur)) return false;
+  writeFileSync(gi, cur + (cur && !cur.endsWith("\n") ? "\n" : "") + "\n# local env (pulled from Wix)\n.env.local\n.env\n");
+  return true;
+}

package/skills/wix-headless-kit/install/install.mjs

@@ -0,0 +1,95 @@
+// The project's one dependency install, decided from what is already on disk. Run from the
+// PROJECT ROOT:
+//
+//   node <SKILL_ROOT>/install/install.mjs            runs it, prints {decision, lock, status}
+//   node <SKILL_ROOT>/install/install.mjs --decide   prints the decision without installing
+//
+// What the lock asks for is compared with node_modules (each entry's package.json version):
+//   none     every entry is there at its version — nothing runs. A machine image that pre-warms the
+//            solutions' packages, or a second deploy that added nothing, ends here in under a second.
+//   install  node_modules exists and holds most of the lock — `npm install --ignore-scripts` keeps what
+//            is there and writes only the difference (seconds for a few packages).
+//   ci       no node_modules, or a tree that lacks most of the lock (the blank starter under a
+//            solution's lock: measured 67 s for ci against 84 s for install there) —
+//            `npm ci --ignore-scripts || npm install --ignore-scripts` (ci needs a lock that agrees
+//            with package.json; without one, install).
+// Every path ends with `.install-exit` holding the exit code (0 for none), the marker setup.mjs,
+// attach.mjs and SKILL.md step 3 sync on. Never two installs concurrently in one project: a second
+// npm in the same node_modules redoes the first one's work.
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { npmSync } from "./proc.mjs";
+
+/** {total, missing, sample}: the lock's node_modules entries the tree lacks or holds at another version. */
+export function lockGaps(projectDir) {
+  const lockPath = join(projectDir, "package-lock.json");
+  if (!existsSync(lockPath)) return null;
+  let lock;
+  try { lock = JSON.parse(readFileSync(lockPath, "utf8")); } catch { return null; }
+  // Optional entries (a platform's native binaries, an optional peer) are absent on every other platform and
+  // npm leaves them out without complaint, so they never count as gaps.
+  const entries = Object.entries(lock.packages ?? {}).filter(([path, e]) => path.startsWith("node_modules/") && !e.link && !e.optional && !e.devOptional);
+  let missing = 0;
+  const sample = [];
+  // A package.json dependency the lock's root entry does not declare (deploy's fill-only patch
+  // added it after the lock was written) is a gap too: the lock no longer describes the project.
+  try {
+    const pkg = JSON.parse(readFileSync(join(projectDir, "package.json"), "utf8"));
+    const root = lock.packages?.[""] ?? {};
+    for (const field of ["dependencies", "devDependencies"]) {
+      for (const name of Object.keys(pkg[field] ?? {})) {
+        if (!(root[field]?.[name] ?? root.dependencies?.[name] ?? root.devDependencies?.[name])) {
+          missing++;
+          if (sample.length < 5) sample.push(`${name} (in package.json, not in the lock)`);
+        }
+      }
+    }
+  } catch { /* no package.json: the lock entries decide */ }
+  for (const [path, e] of entries) {
+    let version = null;
+    try { version = JSON.parse(readFileSync(join(projectDir, path, "package.json"), "utf8")).version; } catch { /* absent */ }
+    if (version !== e.version) {
+      missing++;
+      if (sample.length < 5) sample.push(`${path.replace(/^node_modules\//, "")}@${e.version}${version ? ` (have ${version})` : ""}`);
+    }
+  }
+  return { total: entries.length, missing, sample };
+}
+
+export function installDecision(projectDir = process.cwd()) {
+  const hasModules = existsSync(join(projectDir, "node_modules"));
+  const lock = lockGaps(projectDir);
+  if (!hasModules) return { decision: existsSync(join(projectDir, "package-lock.json")) ? "ci" : "install", lock };
+  if (!lock || lock.total === 0) return { decision: "install", lock };
+  if (lock.missing === 0) return { decision: "none", lock };
+  return { decision: lock.missing > lock.total / 2 ? "ci" : "install", lock };
+}
+
+/** Runs the decided install; stdio defaults to inherited. Returns {decision, lock, status}. */
+export function runInstall(projectDir = process.cwd(), { stdio = "inherit" } = {}) {
+  const { decision, lock } = installDecision(projectDir);
+  const flags = ["--ignore-scripts"];
+  let status = 0;
+  if (decision === "ci") {
+    let r = npmSync("npm", ["ci", ...flags], { cwd: projectDir, stdio });
+    if (r.status !== 0) r = npmSync("npm", ["install", ...flags], { cwd: projectDir, stdio });
+    if (r.error) console.error(`npm could not start: ${r.error.message}`);
+    status = r.status ?? 1;
+  } else if (decision === "install") {
+    const r = npmSync("npm", ["install", ...flags], { cwd: projectDir, stdio });
+    if (r.error) console.error(`npm could not start: ${r.error.message}`);
+    status = r.status ?? 1;
+  }
+  writeFileSync(join(projectDir, ".install-exit"), `${status}\n`);
+  return { decision, lock, status };
+}
+
+if (process.argv[1] && /install\.mjs$/.test(process.argv[1])) {
+  if (process.argv.includes("--decide")) {
+    console.log(JSON.stringify(installDecision(), null, 2));
+  } else {
+    const r = runInstall(process.cwd());
+    console.log(JSON.stringify(r, null, 2));
+    process.exit(r.status);
+  }
+}

package/skills/wix-headless-kit/install/pins.json

@@ -3,6 +3,6 @@
   "@wix/create-new": "0.0.124",
   "typescript": "5.8.3",
   "templates": {
-    "ref": "v1.31.0"
+    "ref": "v1.31.2"
   }
 }

package/skills/wix-headless-kit/install/proc.mjs

@@ -0,0 +1,46 @@
+// npm and npx, started the same way on every OS, and the two detached jobs (the dependency install
+// and the seed) without a POSIX shell.
+//
+// On Windows npm and npx are .cmd shims: Node starts a .cmd only through a shell (ENOENT without
+// one, EINVAL for an explicit .cmd since Node 20.12). npm ships their JS entry points beside
+// node.exe, and those start directly with node. A Node without npm beside it (a version manager's
+// shim) gets the .cmd through cmd.exe, as one quoted command line.
+import { spawn, spawnSync } from "node:child_process";
+import { existsSync, openSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const isWin = process.platform === "win32";
+const BACKGROUND = join(dirname(fileURLToPath(import.meta.url)), "background.mjs");
+
+const cmdQuote = (a) => (/^[\w@%+=:,./\\-]+$/.test(a) ? a : `"${String(a).replace(/"/g, '""')}"`);
+
+/** How to start `npm` or `npx` with `args` here: `{ file, args, shell }` for spawn/spawnSync. */
+export function npmCommand(name, args) {
+  if (!isWin) return { file: name, args, shell: false };
+  const js = join(dirname(process.execPath), "node_modules", "npm", "bin", `${name}-cli.js`);
+  if (existsSync(js)) return { file: process.execPath, args: [js, ...args], shell: false };
+  return { file: [`${name}.cmd`, ...args.map(cmdQuote)].join(" "), args: [], shell: true };
+}
+
+/** spawnSync for npm / npx; same return shape. */
+export function npmSync(name, args, opts = {}) {
+  const c = npmCommand(name, args);
+  return spawnSync(c.file, c.args, { ...opts, shell: c.shell, windowsHide: true });
+}
+
+/** Why a spawnSync result failed: its output, else the spawn error, else the exit status. */
+export const failure = (r, fallback = "") =>
+  String(r.stderr || r.stdout || r.error?.message || fallback || `exit ${r.status ?? r.signal}`);
+
+/**
+ * Starts install/background.mjs detached: `install` (npm ci, else npm install, output to `log`) or
+ * `seed` (node <seed> <plan>: result JSON, log and exit-code marker as files in `cwd`).
+ */
+export function startBackground(job, args, { cwd, log }) {
+  const fd = log ? openSync(log, "a") : "ignore";
+  const child = spawn(process.execPath, [BACKGROUND, job, ...args], {
+    cwd, detached: true, windowsHide: true, stdio: ["ignore", fd, fd],
+  });
+  child.unref();
+}

package/skills/wix-headless-kit/install/setup.mjs

@@ -30,13 +30,15 @@
 // to recover one failed step. Emits ONE JSON event per line and exits in ~35s with the two long
 // steps — the dependency install and the seed — running detached in the background (logs and
 // completion markers in the final event), so the caller can build the brand layer while they finish.
-import { spawn, spawnSync } from "node:child_process";
-import { cpSync, existsSync, openSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { cpSync, existsSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { basename, dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { AGENT_CONFIG_FILES, writeAgentsMd } from "./agents-md.mjs";
+import { ignoreEnvLocal } from "./env-ignore.mjs";
 import { listVerticals, templatesDir } from "./templates.mjs";
 import { folderShape, siteContext } from "./context.mjs";
+import { failure, npmSync, startBackground } from "./proc.mjs";
 const PINS = JSON.parse(readFileSync(new URL("./pins.json", import.meta.url), "utf8"));
 const WIX_CLI = `@wix/cli@${PINS["@wix/cli"]}`;
 
@@ -129,7 +131,7 @@ if (mode === "create") {
     // a committed copy fetches it here, at the commit the rest came from.
     const template = stack === "astro" ? join(templatesDir({ need: `${vertical}/project` }), vertical, "project") : null;
     emit("scaffolding", { folder: folderName, template });
-    const scaffold = spawnSync(
+    const scaffold = npmSync(
       "npm",
       // --skip-git: this wrapper composes its own steps and leaves version control to
       // the caller / the enclosing repo; the scaffold's own `git init` + "Initial
@@ -143,7 +145,7 @@ if (mode === "create") {
       { env: { ...process.env, CI: "1" }, encoding: "utf8", timeout: 300_000 },
     );
     if (scaffold.status !== 0 || !existsSync(join(projectDir, "wix.config.json"))) {
-      fail("scaffold", (scaffold.stderr || scaffold.stdout || `scaffold produced no wix.config.json — is the Wix CLI logged in? (npx ${WIX_CLI} whoami)`).slice(-600));
+      fail("scaffold", failure(scaffold, `scaffold produced no wix.config.json — is the Wix CLI logged in? (npx ${WIX_CLI} whoami)`).slice(-600));
     }
   }
 } else if (mode === "migrate") {
@@ -164,9 +166,6 @@ if (mode === "create") {
     scaffolded.name = basename(cwd).toLowerCase().replace(/[^a-z0-9-]+/g, "-").replace(/^-+|-+$/g, "") || "site";
     writeFileSync(pkgPath, JSON.stringify(scaffolded, null, 2) + "\n");
   }
-  const gi = join(cwd, ".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");
 } else if (publishedStatic) {
   // ---- 1 · a published static site: the config came with the folder, the site exists -------------
   // No init: `wix.config.json` already names the site the pages are published on (and its app). The
@@ -179,10 +178,10 @@ if (mode === "create") {
   // wix.config.json and .env.local, touches nothing else. Non-interactive under CI=1; the site is
   // named after the folder (rename it in the dashboard).
   emit("adopting", { folder: cwd });
-  const init = spawnSync("npm", ["create", `@wix/new@${PINS["@wix/create-new"]}`, "--", "init"],
+  const init = npmSync("npm", ["create", `@wix/new@${PINS["@wix/create-new"]}`, "--", "init"],
     { cwd, env: { ...process.env, CI: "1" }, encoding: "utf8", timeout: 300_000 });
   if (init.status !== 0 || !has("wix.config.json")) {
-    fail("init", (init.stderr || init.stdout || `init produced no wix.config.json — is the Wix CLI logged in? (npx ${WIX_CLI} whoami)`).slice(-600));
+    fail("init", failure(init, `init produced no wix.config.json — is the Wix CLI logged in? (npx ${WIX_CLI} whoami)`).slice(-600));
   }
 }
 const wixConfig = JSON.parse(readFileSync(join(projectDir, "wix.config.json"), "utf8"));
@@ -208,7 +207,7 @@ const deploy = spawnSync(
   [join(SKILL_ROOT, "install", "deploy.mjs"), ...verticals, "--stack", stack, ...(stack === "static" ? ["--out", STATIC_OUT] : []), ...(planPath ? ["--plan", resolve(planPath)] : [])],
   { cwd: projectDir, encoding: "utf8", timeout: 60_000 },
 );
-if (deploy.status !== 0) fail("deploy", deploy.stderr || deploy.stdout);
+if (deploy.status !== 0) fail("deploy", failure(deploy));
 let deployResult = {};
 try { deployResult = JSON.parse(deploy.stdout); } catch { /* keep going with raw output below */ }
 if (deployResult.error) fail("deploy", deployResult.error);
@@ -243,7 +242,10 @@ if (mode === "create" && !subfolder && projectDir !== cwd) {
   }
 }
 
-// ---- 2d · the agent config files `wix create` would have written --------------------------------
+// ---- 2d · .env.local ignored, and the agent config files `wix create` would have written ---------
+// Every mode leaves a .env.local with the app secret (env pull, init, the migration download), and a
+// folder's own .gitignore may not cover it.
+ignoreEnvLocal(projectDir);
 // Skipped by the CLI because of --skip-install. Fill-only: a project that has its own AGENTS.md
 // keeps it (the event says `kept`).
 emit("agent_configs", writeAgentsMd(projectDir, { skill: basename(SKILL_ROOT), stack, ...(migrating ? { migration: { parentSiteId: ctx.migration.parentSiteId, deploySiteId: ctx.deploy.siteId } } : {}) }));
@@ -255,14 +257,8 @@ emit("agent_configs", writeAgentsMd(projectDir, { skill: basename(SKILL_ROOT), s
 let install = null;
 if (stack !== "static" && 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" };
+  startBackground("install", [], { cwd: projectDir, log: installLog });
+  install = { log: installLog, doneMarker: ".install-exit", success: "file contains 0" };
   emit("install_started", install);
 }
 
@@ -276,7 +272,7 @@ if (stack !== "static" && existsSync(join(projectDir, "package.json"))) {
 const madeTheSite = mode === "create" || mode === "adopt";
 let seed = null;
 if (planPath && !madeTheSite) {
-  emit("seed_skipped", { reason: `${mode}: the site existed before this run; setup seeds only a site it created. Read what the site holds (templates/${vertical}/seed/read-site.mjs), then run templates/${vertical}/seed/seed-*.mjs ${planPath} yourself when the brief supplies or describes content` });
+  emit("seed_skipped", { reason: `${mode}: the site existed before this run; setup seeds only a site it created. Read what the site holds (${join(TEMPLATES, vertical, "seed", "read-site.mjs")}), then run templates/${vertical}/seed/seed-*.mjs ${planPath} yourself when the brief supplies or describes content` });
 }
 if (planPath && madeTheSite) {
   const seedDir = join(TEMPLATES, vertical, "seed");
@@ -286,12 +282,7 @@ if (planPath && madeTheSite) {
   if (!seedName) fail("seed", `no seed module found under ${seedDir}`);
   const seedFile = join(seedDir, seedName);
   const planAbs = resolve(planPath);
-  const seedChild = spawn(
-    "sh",
-    ["-c", `node "${seedFile}" "${planAbs}" > seed-result.json 2> seed.log; echo $? > .seed-exit`],
-    { cwd: projectDir, detached: true, stdio: "ignore" },
-  );
-  seedChild.unref();
+  startBackground("seed", [seedFile, planAbs], { cwd: projectDir });
   seed = { resultFile: "seed-result.json", log: "seed.log", doneMarker: ".seed-exit", success: "file contains 0" };
   emit("seeding_started", { vertical, ...seed, ...(verticals.length > 1 ? { note: `the plan seeds ${vertical}; the other verticals' seeds run afterwards, each with its own plan` } : {}) });
 }
@@ -325,7 +316,7 @@ emit("ready_for_brand_layer", {
       ? "a migration preview: the site being migrated owns its content (read it with the vertical's read-site.mjs when the brief allows probing; never seed it); theme + write the home page; "
       : madeTheSite
       ? (planPath ? "theme + write the home page; " : "the site is new and empty and no plan was given, so nothing was seeded yet: seed it now (a plan per step 2 — the brief's content, or one drafted per the vertical's SEED.md — then the vertical's seed module), and name the placeholder content in the closing message; theme + write the home page; ")
-      : `nothing was seeded (setup seeds only a site it created): read what the site holds with templates/${vertical}/seed/read-site.mjs, then run templates/${vertical}/seed/seed-*.mjs <plan> when the brief supplies or describes content; theme + write the home page; `) +
+      : `nothing was seeded (setup seeds only a site it created): read what the site holds with ${join(TEMPLATES, vertical, "seed", "read-site.mjs")}, then run ${join(TEMPLATES, vertical, "seed")}/seed-*.mjs <plan> when the brief supplies or describes content; theme + write the home page; `) +
     (others.length && mode !== "migrate"
       ? `${others.join(", ")} deployed too, no further install needed: run each one's seed module (templates/<vertical>/seed/) with its own plan when the brief gives it content (the members seed installs the Members Area app and needs no plan); `
       : "") +

package/skills/wix-headless-kit/install/templates.mjs

@@ -7,7 +7,8 @@
 //
 // Resolution, in order:
 //   1. the sibling skill folder, `<SKILL_ROOT>/../wix-headless-templates/`: a checkout of the repository,
-//      or a plugin install that carries both skills (every plugin manifest lists the templates skill).
+//      or an install that carries both skills (the cold start's `npx skills add`, the npm package,
+//      the Codex and Cursor plugins; the Claude plugin leaves it out, so there it is fetched).
 //   2. the cache `<SKILL_ROOT>/templates/`, filled by an earlier call (`--refresh` refetches).
 //   3. a fetch: a sparse, shallow clone of `skills/wix-headless-templates/` from the repository the skill was installed
 //      from (skills-lock.json's `source`, default wix/skills), at the branch or tag the install
@@ -25,7 +26,7 @@
 // `need`; when a committed copy lacks it, that part is fetched at the same commit.
 import { cpSync, existsSync, mkdtempSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
-import { dirname, join, resolve } from "node:path";
+import { basename, dirname, join, resolve } from "node:path";
 import { spawnSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
 
@@ -42,7 +43,7 @@ const git = (args, opts = {}) => spawnSync("git", args, { encoding: "utf8", time
 // skill folder, its entry for this skill. "wix/skills" → the default branch of that repository;
 // "https://github.com/owner/repo/tree/<ref>" → that ref.
 export function installSource() {
-  const skill = SKILL_ROOT.split("/").pop();
+  const skill = basename(SKILL_ROOT);
   let dir = SKILL_ROOT;
   for (let i = 0; i < 6; i++) {
     const p = join(dir, "skills-lock.json");

package/skills/wix-headless-templates/blog/app/components/blog/RichContent.tsx

@@ -1,12 +1,13 @@
 // The post-body renderer — wire AS-IS (machinery, not a reference). A post body is a Ricos
 // document, not HTML and not text: never innerHTML it, never String() its nodes. This is the
-// documented render path (@wix/ricos viewer + quick-start plugins).
+// documented render path (@wix/ricos/viewer + quick-start plugins: the viewer-only entry, 11.17+,
+// without the editor, its dev tools and CodeMirror that the root import drags into every bundle).
 //
 // In Astro this component MUST be a `client:only="react"` island — the ricos viewer breaks
 // under SSR. Dark theme: the ricos CSS hardcodes near-black text; scope an override on
 // `.ricos-content` forcing the foreground token (in Astro use <style is:global> — React
 // islands don't inherit scoped Astro styles).
-import { quickStartViewerPlugins, RicosViewer } from "@wix/ricos";
+import { quickStartViewerPlugins, RicosViewer } from "@wix/ricos/viewer";
 import "@wix/ricos/css/all-plugins-viewer.css";
 
 // Module-level, once — never rebuild the plugin list per render.