@wix/agent-skills 1.24.0 → 1.26.0

package/skills/wix-headless/scripts/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-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-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-kit/SKILL.md

@@ -86,10 +86,10 @@ doesn't express — or once the site exists and the work turns to managing or ex
 
 Needed throughout: Node ≥ 20.11, git, a logged-in Wix CLI (`npx @wix/cli@latest whoami`;
 `npx @wix/cli@latest login` is a device-code flow: surface the URL and code to the user, never
-read tokens into context), and the two companion skills beside this one, `wix-docs` and
-`wix-manage` (if `.agents/skills/` lacks them:
-`CI=1 npx skills@latest add wix/skills --skill wix-docs --skill wix-manage --yes`). The cold-start
-page, `cold-start/cold-start.md`, gets a machine with none of this to that point. In a folder that
+read tokens into context), and the two companion skills installed beside this one, `wix-docs`
+and `wix-manage`. `node <SKILL_ROOT>/install/bootstrap.mjs` checks the CLI and runs the login
+when there is none; the cold-start page, `https://www.wix.com/skills/headless-cold-start/headless-kit.md`,
+gets a machine with none of this, the skills included, to that point. In a folder that
 already holds a `wix.config.json`, `node <SKILL_ROOT>/install/context.mjs` first: it runs
 `wix env pull` when `.env.local` is missing and prints the folder's **shape** (`folder.shape`, the
 cases of step 3, with the `next` for each) and the two identities a project has — the deploy site

package/skills/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

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-kit/install/check.mjs

@@ -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-manage/SKILL.md

@@ -135,19 +135,13 @@ Uses Calendar Events API to create WORKING_HOURS events on the business schedule
 ## CMS
 
 ### [CMS Data Items CRUD](references/cms/cms-data-items-crud.md)
-"Add, query, update, and delete items in CMS collections. Use this to insert content, bulk insert/update/patch/delete items, query with filters, and manage collection data. Key endpoints: /wix-data/v2/items, /wix-data/v2/bulk/items/*."
-
-### [CMS Data Operations Extended](references/cms/cms-data-operations-extended.md)
-Additional CMS data operations including count, upsert (bulk save), and update by filter patterns.
+"Add, query, update, and delete items in CMS collections, one at a time or in bulk. Also covers counting items, upserting with bulk save, truncating a collection, aggregating data with a pipeline, linking items through single- and multi-reference fields, and reading items with their referenced items expanded."
 
 ### [CMS eCommerce Catalog Integration](references/cms/cms-ecommerce-catalog-integration.md)
 The recommended way to sell existing CMS collection items (tickets, bookings, memberships) through Wix checkout. Add the CATALOG plugin to convert any CMS collection into purchasable products with cart and payment integration.
 
-### [CMS References And Relationships](references/cms/cms-references-and-relationships.md)
-"Add, replace, or remove items from MULTI_REFERENCE fields. Use insert-references, replace-references, remove-references endpoints. Required for managing multi-reference relationships - these CANNOT be set via regular insert/update/patch operations. Also covers single references and querying with expanded references."
-
 ### [CMS Schema Management](references/cms/cms-schema-management.md)
-Create and modify CMS collection structures. Covers listing collections, creating collections with fields, adding/removing fields, and updating collection settings.
+Create and modify CMS collection structures. Covers listing collections, creating collections with fields, adding/removing fields (including single- and multi-reference fields that link two collections), and updating collection settings.
 
 ### [CMS Draft & Publish Workflow (Draft Items plugin)](references/cms/cms-publishing-flow.md)
 "Interact with CMS collections that gate their items behind a draft/publish workflow via the Draft Items plugin. Covers detecting the plugin, locating the paired drafts collection, reading published vs draft items, authoring/editing drafts, and publishing, unpublishing, reverting, and deleting items. Key endpoints: /wix-data/v2/items/publish-draft, /wix-data/v2/items/unpublish, /wix-data/v2/collections/add-draft-items-plugin, and the paired drafts collection referenced by draftItemsPluginOptions.draftsCollectionId."