@wix/agent-skills 1.23.0 → 1.25.0

package/skills/{wix-headless-fast → wix-headless-kit}/install/AGENTS.md

@@ -17,8 +17,8 @@ call is memory, and an empty or error reply to it says nothing about the site.
 
 ## Skills
 
-Installed at `.agents/skills/`. If missing, restore with:
-`CI=1 npx skills@latest add wix/skills --skill {{SKILL}} --skill wix-docs --skill wix-manage --yes`
+Installed at `.agents/skills/` (by the Wix plugin, or by
+`npx skills add wix/skills --skill {{SKILL}} --skill wix-docs --skill wix-manage`).
 
 - `{{SKILL}}` — the code in this app and how to extend it. The shipped code sits in
   `.agents/skills/{{SKILL}}/templates/`, fetched once from the skill's repository and kept with this
@@ -29,6 +29,9 @@ Installed at `.agents/skills/`. If missing, restore with:
   site holds for it, with the documentation URL of every call it made. A code change ends with a release; the live URL shows it, the dev server does not count.
   `node .agents/skills/{{SKILL}}/install/check.mjs` says whether the skill or its templates have a newer
   version and prints the update commands; an update touches the skill folder or `templates/`, never `src/`.
+  When Wix gets in the way of a change here (a confusing error, a doc gap, a workaround you had to
+  invent), offer to relay it to Wix per `.agents/skills/{{SKILL}}/guides/feedback.md`; send only after
+  an explicit yes.
 - `wix-docs` — how to discover the Wix APIs and their docs: search first, then read only the page
   you need. Every endpoint, body, field and enum you did not get from the deployed code or a recipe
   is confirmed there before you write it.

package/skills/{wix-headless-fast → wix-headless-kit}/install/attach.mjs

@@ -45,7 +45,7 @@ import { cpSync, existsSync, mkdirSync, openSync, readFileSync, writeFileSync }
 import { basename, dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { writeAgentsMd } from "./agents-md.mjs";
-import { siteContext } from "./context.mjs";
+import { frontendPresent, siteContext } from "./context.mjs";
 import { listVerticals, templatesDir } from "./templates.mjs";
 
 const SKILL_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
@@ -76,7 +76,10 @@ const subfolder = argv.includes("--subfolder");
 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");
+// A frontend here: a package.json, an index.html at the root, or an index.html in the folder the
+// config's site.outputDirectory names (a static site laid out for release) — install/context.mjs.
+const fp = frontendPresent(cwd);
+const hasProject = fp.packageJson || fp.rootIndex || fp.outputIndex;
 // A migration preview (wix.config.json names a deploy-only site, .env.local names the site being
 // migrated) is already provisioned: its app, hosting and credentials came with the folder. Nothing
 // here applies — setup.mjs takes it (SKILL.md step 3).

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

@@ -0,0 +1,156 @@
+#!/usr/bin/env node
+import { spawn, spawnSync } from 'node:child_process';
+import { existsSync, mkdirSync, openSync, readFileSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+// ── tiny event protocol (one JSON object per line) ───────────────────────────
+const emit = (event, extra = {}) =>
+  process.stdout.write(JSON.stringify({ event, ...extra }) + '\n');
+const fail = (event, extra = {}) => {
+  emit(event, { ok: false, ...extra });
+  process.exit(1);
+};
+
+// ── platform-safe binary names (npm/npx are .cmd on Windows) ─────────────────
+const isWin = process.platform === 'win32';
+const bin = (name) => (isWin ? `${name}.cmd` : name);
+const WIX = [bin('npx'), '-y', '@wix/cli@latest']; // run the CLI via npx — no global install/mutation
+
+// Force the CLI into non-interactive "agent" mode. Without an agent signal in
+// the env, `wix login` renders an interactive Ink TUI (device code + keypress)
+// that needs a raw TTY and crashes in an agent sandbox — and it never emits the
+// JSON login events this script forwards. The CLI uses @vercel/detect-agent,
+// whose first check is the AI_AGENT env var, so setting it guarantees agent mode
+// (and the awaiting_user/success/logged_in events) for every child we spawn.
+// Respect an existing value so a known runner (claude, cursor, …) keeps its name.
+const AGENT_ENV = { ...process.env, AI_AGENT: process.env.AI_AGENT || 'wix-headless-kit-skill' };
+
+// Where the detached login parks its output between runs. It has to outlive this
+// process, so it can't be a pipe and can't live in the project.
+const STATE_DIR = join(tmpdir(), 'wix-headless-kit-login');
+const LOG = join(STATE_DIR, 'login.log');
+const PIDFILE = join(STATE_DIR, 'login.pid');
+
+// run a command, capture stdout+stderr (combined), return {status, out}
+function capture(cmd, args, opts = {}) {
+  const r = spawnSync(cmd, args, { encoding: 'utf8', shell: isWin, env: AGENT_ENV, ...opts });
+  return { status: r.status ?? 1, out: `${r.stdout || ''}${r.stderr || ''}`, error: r.error };
+}
+
+// ── 1. CLI reachable (via npx — no install) ──────────────────────────────────
+function checkCli() {
+  const r = capture(WIX[0], [...WIX.slice(1), '--version']);
+  if (r.status !== 0) fail('cli_unreachable', { detail: r.out.trim().slice(0, 400) });
+  // npx interleaves "npm notice …" lines with the version, so don't just take the
+  // last line — pick the first semver-looking token, falling back to the last line.
+  const version = (r.out.match(/\d+\.\d+\.\d+[^\s]*/) || [])[0] || r.out.trim().split('\n').pop();
+  emit('cli_ok', { version });
+}
+
+// ── 2. Reuse an existing session, or start device login ──────────────────────
+const hasExistingSession = () => capture(WIX[0], [...WIX.slice(1), 'whoami']).status === 0;
+
+function loginEvents() {
+  if (!existsSync(LOG)) return [];
+  return readFileSync(LOG, 'utf8')
+    .split('\n')
+    .map((l) => l.trim())
+    .filter(Boolean)
+    .map((l) => {
+      try {
+        return JSON.parse(l);
+      } catch {
+        return null; // non-JSON CLI chatter
+      }
+    })
+    .filter((e) => e && e.event);
+}
+
+const alive = (pid) => {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+// A login this machine started earlier may still be waiting on the browser. Reuse
+// its code instead of minting a second one — a new login invalidates nothing, but
+// it hands the user a different code than the one already on their screen.
+function pendingLogin() {
+  if (!existsSync(PIDFILE)) return null;
+  let state;
+  try {
+    state = JSON.parse(readFileSync(PIDFILE, 'utf8'));
+  } catch {
+    return null;
+  }
+  if (!state.pid || !alive(state.pid)) return null;
+  const ev = loginEvents().find((e) => e.event === 'awaiting_user');
+  if (!ev) return null;
+  // Don't hand back a code that's about to expire mid-typing.
+  const ageSeconds = Math.round((Date.now() - state.startedAt) / 1000);
+  if (ageSeconds > (ev.expiresInSeconds ?? 600) - 60) return null;
+  return ev;
+}
+
+// Detach so the login keeps polling after this process exits. stdio goes to a
+// file, not a pipe: a pipe dies with the parent, and the CLI would get EPIPE.
+function startLogin() {
+  mkdirSync(STATE_DIR, { recursive: true });
+  writeFileSync(LOG, '');
+  const out = openSync(LOG, 'a');
+  const child = spawn(WIX[0], [...WIX.slice(1), 'login'], {
+    detached: true,
+    stdio: ['ignore', out, out],
+    env: AGENT_ENV,
+    shell: isWin,
+  });
+  child.on('error', (e) => fail('login_failed', { detail: String(e) }));
+  writeFileSync(PIDFILE, JSON.stringify({ pid: child.pid, startedAt: Date.now() }));
+  child.unref();
+}
+
+async function waitForCode(timeoutMs = 60000) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    const events = loginEvents();
+    const ev = events.find((e) => e.event === 'awaiting_user');
+    if (ev) return ev;
+    const bad = events.find((e) => e.event === 'login_failed');
+    if (bad) fail('login_failed', bad);
+    await new Promise((r) => setTimeout(r, 500));
+  }
+  const detail = existsSync(LOG) ? readFileSync(LOG, 'utf8').trim().slice(-1500) : '';
+  fail('login_failed', {
+    detail: detail || `wix login produced no device code within ${timeoutMs / 1000}s.`,
+  });
+}
+
+// The next move is the user's, so hand the code back and exit rather than holding
+// the caller open for a browser round-trip. `message` is the sentence to relay.
+function surrenderTo(ev) {
+  emit('awaiting_user', {
+    ...ev,
+    message:
+      `To connect your Wix account, open ${ev.verificationUri} and enter the code ` +
+      `${ev.userCode}. Tell me once you're done and I'll continue.`,
+  });
+  process.exit(0);
+}
+
+// ── main ────────────────────────────────────────────────────────────────────
+checkCli();
+
+if (hasExistingSession()) {
+  emit('logged_in');
+  process.exit(0);
+}
+
+const pending = pendingLogin();
+if (pending) surrenderTo(pending);
+
+startLogin();
+surrenderTo(await waitForCode());

package/skills/{wix-headless-fast → wix-headless-kit}/install/check.mjs

@@ -24,7 +24,7 @@ const { repo } = installSource();
 const out = { skill: {}, templates: {}, update: {} };
 
 // ---- the repository: one clone of its history without file contents (small), read for both layers
-const tmp = mkdtempSync(join(tmpdir(), "wix-headless-fast-check-"));
+const tmp = mkdtempSync(join(tmpdir(), "wix-headless-kit-check-"));
 const clone = git(["clone", "--quiet", "--filter=blob:none", "--no-checkout", "--single-branch", repo, tmp]);
 if (clone.status !== 0) {
   rmSync(tmp, { recursive: true, force: true });
@@ -80,7 +80,7 @@ rmSync(tmp, { recursive: true, force: true });
 // ---- what would act on each ------------------------------------------------------------------
 const rel = relative(process.cwd(), SKILL_ROOT) || ".";
 out.update = {
-  skill: `CI=1 npx skills@latest update ${skillName} --yes   (or: gh skill update ${skillName})`,
+  skill: `update ${skillName} the way it was installed (the plugin's update, or the skills CLI's)`,
   templates: `node ${rel}/install/templates.mjs --refresh   (then commit the changed files under ${rel}/templates)`,
   note: "neither touches src/; a shipped fix reaches the project by comparing its copy with the template",
 };

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

@@ -0,0 +1,169 @@
+// The site context of a project folder — the one place that says which site a call targets.
+//
+//   node <SKILL_ROOT>/install/context.mjs [--refresh] [--no-pull]     (prints one JSON object)
+//
+// Two identities live in a Wix project and are the same site almost always:
+//   deploy  — `wix.config.json` (`siteId`, `appId`): where `wix release` uploads. The CLI's business.
+//   content — `.env.local` (`WIX_CLIENT_ID`, what `wix env pull` writes): the app the SDK client
+//             runs as, on every stack (the Astro integration reads WIX_CLIENT_ID from the env and
+//             never the config; the other stacks get it copied into src/wix/config.ts by deploy.mjs).
+// They differ on a MIGRATION PREVIEW: a project whose config points at a fresh site created only to
+// host the deployment, while `.env.local` carries the credentials of the site being migrated (the
+// parent) and says so. Then every admin, discovery and seed call targets the parent, the SDK client
+// is the parent's, and only the release goes to the child. Completing the migration is a CLI step
+// that does not exist yet; this module only reads the state.
+//
+// `env pull` runs here when `.env.local` is missing (or --refresh): it is the source of the content
+// identity, and the Astro build refuses to run without it. Non-interactive (CI=1); a failure is
+// reported in `pullError` and the config's ids stand in, so a caller can still work offline.
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+// The variables the editor-to-headless migration writes into the child project's `prod`
+// environment (headless-bo, editorMigrations/environmentMetadata.ts), which `wix env pull` copies
+// into `.env.local` unchanged. The names are the platform's and are spelled once, here.
+export const ENV = {
+  clientId: "WIX_CLIENT_ID",
+  parentSiteId: "EDITOR_MIGRATION_PARENT_SITE_ID",
+  /** ACTIVE while the migration is under way; COMPLETED once the parent serves the child's frontend. */
+  status: "EDITOR_MIGRATION_STATUS",
+  childSiteId: "EDITOR_MIGRATION_CHILD_SITE_ID",
+  childAppId: "EDITOR_MIGRATION_CHILD_APP_ID",
+};
+
+/** KEY=value lines of a dotenv file, quotes stripped; null when the file is absent. */
+export function readEnvFile(file) {
+  if (!existsSync(file)) return null;
+  const out = {};
+  for (const raw of readFileSync(file, "utf8").split(/\r?\n/)) {
+    const line = raw.trim();
+    if (!line || line.startsWith("#")) continue;
+    const eq = line.indexOf("=");
+    if (eq === -1) continue;
+    const key = line.slice(0, eq).trim().replace(/^export\s+/, "");
+    let value = line.slice(eq + 1).trim();
+    if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+      value = value.slice(1, -1).replace(/\\"/g, '"');
+    }
+    out[key] = value;
+  }
+  return out;
+}
+
+export function readWixConfig(cwd) {
+  const file = join(cwd, "wix.config.json");
+  if (!existsSync(file)) return null;
+  try { return JSON.parse(readFileSync(file, "utf8")); } catch { return null; }
+}
+
+const ENV_PULL = ["-y", "@wix/cli@latest", "env", "pull"];
+const runPull = (dir) => spawnSync("npx", ENV_PULL, { cwd: dir, env: { ...process.env, CI: "1" }, encoding: "utf8", timeout: 180_000 });
+
+/**
+ * `wix env pull` into `cwd/.env.local`, in place. Every project shape gets the command since Wix CLI
+ * 1.1.253 (2026-09-29): before it, a config with `site.outputDirectory` (the static stack, a site
+ * published through the drop flow) landed in a limited command set without `env`, and this pulled
+ * through a temp copy of the config. Non-interactive; a failure comes back as `error`.
+ */
+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@latest 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
+ * 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()) {
+  const has = (p) => existsSync(join(cwd, p));
+  const outDir = (readWixConfig(cwd)?.site?.outputDirectory ?? "").replace(/^\.\//, "").replace(/\/$/, "");
+  return {
+    packageJson: has("package.json"),
+    rootIndex: has("index.html"),
+    outputIndex: !!outDir && outDir !== "." && has(join(outDir, "index.html")),
+    outputDirectory: outDir || null,
+  };
+}
+
+/**
+ * What the folder IS, from five 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`).
+ *
+ *   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
+ *   config-only       a config, no frontend → attach.mjs on the config's site; nothing seeded
+ *   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
+ *   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
+ *                     published through the drop flow and downloaded) → setup makes site/ the upload and
+ *                     deploys the REST layer; the config's site, no init, nothing seeded
+ */
+export function folderShape(cwd = process.cwd(), { migrationActive = false } = {}) {
+  const config = existsSync(join(cwd, "wix.config.json"));
+  const f = frontendPresent(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",
+    "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.outputIndex) shape = "wix-project";
+  else if (f.rootIndex) shape = "published-static";
+  else shape = "config-only";
+  return { shape, next: next[shape], facts: { config, ...f } };
+}
+
+/**
+ * `{ folder: { shape, next, tells }, deploy: { siteId, appId }, content: { siteId, clientId },
+ *    migration: { active, parentSiteId }, env: { file, present, pulled }, pullError?, warnings: [] }`.
+ * `pull`: "auto" (default) pulls when `.env.local` is missing; true always; false never.
+ */
+export function siteContext({ cwd = process.cwd(), pull = "auto" } = {}) {
+  const config = readWixConfig(cwd) ?? {};
+  const deploy = { siteId: config.siteId ?? config.projectId ?? null, appId: config.appId ?? null };
+  const envFile = join(cwd, ".env.local");
+  let pulled = false, pullError;
+  if (deploy.siteId && (pull === true || (pull === "auto" && !existsSync(envFile)))) {
+    const r = pullEnv(cwd);
+    if (r.ok) pulled = r.via;
+    else pullError = r.error;
+  }
+  const env = readEnvFile(envFile) ?? {};
+  const parentSiteId = env[ENV.parentSiteId] || null;
+  const status = env[ENV.status];
+  // ACTIVE (or a parent id with no status yet) is a migration under way; COMPLETED means the parent
+  // already serves this frontend and the project is an ordinary one again.
+  const active = !!parentSiteId && (status === undefined || status.trim().toUpperCase() === "ACTIVE");
+  const migration = { active, parentSiteId: active ? parentSiteId : null, ...(status ? { status: status.trim().toUpperCase() } : {}) };
+  const clientId = env[ENV.clientId] || deploy.appId;
+  const content = { siteId: active ? parentSiteId : deploy.siteId, clientId };
+  const warnings = [];
+  if (env[ENV.clientId] && deploy.appId && env[ENV.clientId] !== deploy.appId && !active && migration.status !== "COMPLETED") {
+    warnings.push(`.env.local ${ENV.clientId} differs from wix.config.json appId and no migration is declared — the SDK client runs as the env's app, the release goes to the config's site`);
+  }
+  if (active && migration.parentSiteId === deploy.siteId) {
+    warnings.push("the migration's parent site is the deploy site itself — nothing is being migrated");
+  }
+  return { folder: folderShape(cwd, { migrationActive: active }), deploy, content, migration, env: { file: envFile, present: Object.keys(env).length > 0, pulled }, ...(pullError ? { pullError } : {}), warnings };
+}
+
+// ---- CLI ----------------------------------------------------------------------------------------
+if (process.argv[1] && /context\.mjs$/.test(process.argv[1])) {
+  const argv = process.argv.slice(2);
+  const pull = argv.includes("--no-pull") ? false : argv.includes("--refresh") ? true : "auto";
+  console.log(JSON.stringify(siteContext({ pull }), null, 2));
+}

package/skills/{wix-headless-fast → wix-headless-kit}/install/deploy.mjs

@@ -111,6 +111,18 @@ const VERTICAL_DEPS = {
       "@wix/essentials": "^1.0.6",
     },
   },
+  rentals: {
+    // A rental is a Bookings service with rentals-specific values: the same SDK modules as bookings.
+    core: {
+      "@wix/bookings": "^1.0.1650",
+      "@wix/auto_sdk_ecom_cart-v-2": "^1.0.192",
+      "@wix/redirects": "^1.0.125",
+    },
+    astro: {
+      "@wix/seo": "^1.0.79",
+      "@wix/essentials": "^1.0.6",
+    },
+  },
   blog: {
     core: {
       "@wix/blog": "^1.0.645",
@@ -247,7 +259,7 @@ if (siteSearch) {
 }
 // The generated file is data only; the shipped core resolves defaults (types, routes, labels) from it.
 const siteSearchConfigSource = () =>
-  `// Generated by wix-headless-fast install/deploy.mjs from plan.capabilities.siteSearch.\n` +
+  `// Generated by wix-headless-kit install/deploy.mjs from plan.capabilities.siteSearch.\n` +
   `// Edit the plan and redeploy. Defaults for anything omitted are in search-core.ts (resolveConfig).\n` +
   `export const siteSearchPlan = ${JSON.stringify(siteSearch, null, 2)};\n`;
 // ---- static stack: the REST layer, composed flat and stripped ------------------------------------
@@ -401,7 +413,7 @@ if (uploadPolicies.length) {
   // The generated file is data only. The shipped endpoint owns validation and elevation.
   writeFileSync(
     configFile,
-    `// Generated by wix-headless-fast install/deploy.mjs from plan.capabilities.mediaUpload.\n` +
+    `// Generated by wix-headless-kit install/deploy.mjs from plan.capabilities.mediaUpload.\n` +
       `// Edit the plan and redeploy; do not add browser-controlled policy selection here.\n` +
       `export const mediaUploadPolicies = ${JSON.stringify(uploadPolicies, null, 2)} as const;\n`,
   );
@@ -506,8 +518,9 @@ if (!requested.length) {
 }
 
 // ---- client ids ---------------------------------------------------------------------------------
-// The shared data client is ambient on managed Astro. Members are different: their shipped
-// custom credential flow always needs an explicit public OAuth client, including on Astro.
+// The shared data client is ambient on managed Astro, and so is the members flow there (the
+// integration's built-in /api/auth routes). WIX_MEMBERS_CLIENT_ID is still filled for projects whose
+// members code predates the shared seam; the shipped code reads WIX_CLIENT_ID only.
 // --client-id, else the CONTENT app: .env.local's WIX_CLIENT_ID (what `wix env pull` writes — on a
 // migration preview the parent site's app, the one the Astro integration itself runs as), else the
 // config's appId. Never the config first: on a preview that is the deploy-only child app.