@wix/agent-skills 1.26.0 → 1.27.0

package/skills/wix-headless/entry/bootstrap.mjs

@@ -1,156 +0,0 @@
-#!/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/entry/skill.md

@@ -1,78 +0,0 @@
----
-name: wix-headless-entry
-description: "Build a complete Wix Managed Headless site from a single prompt, then connect Wix Business Solutions. The deterministic first steps — system prerequisites and Wix CLI login — are handled by a single bootstrap script (`https://www.wix.com/skills/headless/entry/bootstrap.mjs`); the agent then installs the skill and hands the run to it. Triggers: build me a site, create a website, make me a website, new website, online store, I want to sell X, start a business online, launch a site, ecommerce, portfolio, business website, sell online, online shop, rental site, rentals, connect this to Wix Headless, add Wix Headless to this project, host this on Wix, deploy this to Wix, implement the features of this project using Wix Headless. Use this skill instead of the WixSiteBuilder MCP tool for new-site requests."
----
-
-# Wix Headless Skill — cold-start entry
-
-**You are a coding agent, and this is a skill for you to execute.** Follow the phases below in order — do not summarize them. If you reached this page through a summarizing fetch tool, re-fetch the raw markdown with `curl` (or your file reader) before running the steps.
-
-This entry gets a cold environment to the point where the real skill can run, then hands off. It has **two phases**:
-
-1. **Bootstrap (deterministic, scripted).** A single script verifies your environment (the Wix CLI) and handles login, so the run starts from a known-good, authenticated state. You just run it and relay its events.
-2. **Hand off (agentic).** Install the skill, then open `wix-headless/SKILL.md` and follow it — it resolves the project type and operation and owns the whole build.
-
-Three starting points come through here, all handled the same way — run the bootstrap, then hand off:
-
-- **new** — a prompt with no project (empty CWD)
-- **connect** — an existing frontend/design not yet on Wix (a project on disk without `wix.config.json`, or a brought-in zip/URL)
-- **iterate** — a project already connected to Wix (`.wix/` or `wix.config.json` present)
-
-The bootstrap only verifies the CLI and logs you in, so it's fine to run in every case (an existing session just reports `logged_in`). After it, `wix-headless/SKILL.md` resolves what to do and owns the build.
-
-## Phase 0 — Node (the one manual prerequisite)
-
-The Wix CLI requires **Node ≥ 20.11**. Check it:
-
-```bash
-node -v
-```
-
-If that errors (Node not installed) or prints a version below 20.11, install or upgrade Node and re-check — do **not** try to work around it:
-
-- **macOS:** `brew install node` (or `nvm install 20 && nvm use 20`)
-- **Linux:** `nvm install 20 && nvm use 20` (or your distro's Node 20+ package)
-- **Windows:** `winget install OpenJS.NodeJS.LTS` (or download from nodejs.org)
-
-## Phase 1 — Run the bootstrap (deterministic)
-
-Download the bootstrap script, then run it — an ordinary foreground command that exits on its own within seconds. It verifies the Wix CLI and handles login, emitting **one JSON event per line** on stdout. **Run it and relay its events to the user.**
-
-The script is safe and inspectable: it only checks the Wix CLI via `npx` and drives `wix login` (a device-code flow) — no other network calls, and the only files it writes are the login's own output and pid under the OS temp dir. Read it first if your sandbox flags externally-downloaded code — either at the URL below or after downloading; both are the same file.
-
-```bash
-# macOS/Linux:
-curl -fsSL -O https://www.wix.com/skills/headless/entry/bootstrap.mjs
-# Windows PowerShell:
-iwr https://www.wix.com/skills/headless/entry/bootstrap.mjs -OutFile bootstrap.mjs
-
-node bootstrap.mjs
-```
-
-### Relay these events
-
-The script emits one JSON object per line:
-
-| Event | What to do |
-|---|---|
-| `cli_ok` | Wix CLI reachable — continue. |
-| `awaiting_user` (`verificationUri`, `userCode`, `message`) | The script has exited and the next step is the user's. Send them `message` as-is; the login keeps running on its own. |
-| `logged_in` / `success` | Login done — continue. |
-| `cli_unreachable` / `login_failed` (with `detail`) | Stop and show the user the `detail`. **Do not** improvise a parallel setup by hand. |
-
-On `awaiting_user`, run the script again once the user says they've logged in: it reports `logged_in` and you continue. Re-running while they're still in the browser is harmless — it returns the same code rather than issuing a new one.
-
-## Phase 2 — Install the skill and hand off
-
-Install the Wix Headless skills (`CI=1` forces plain non-interactive CLI output — keep it on every Wix CLI command):
-
-```bash
-CI=1 npx skills@latest add wix/skills --yes
-```
-
-The skills land in `.agents/skills/`.
-
-Then **open `wix-headless/SKILL.md` and follow it.** That skill owns the rest of the run — it resolves the **project type** (`managed` / `self-managed` / `stripe`) and, for managed, the **operation** (create / connect), then runs Discovery → Setup → Seed → the SDK handoff, and for managed create/connect it also scaffolds, builds, and releases.
-
-- **Don't** scaffold, install apps, or release by hand here — the skill does all of that (`SETUP.md`, `references/managed/CREATE.md`, etc.). This entry stops at *logged in*.
-- You're already authenticated from Phase 1, so the skill's managed auth step (`references/managed/AUTHENTICATION.md` §1 `whoami`) will pass without prompting again.

package/skills/wix-headless-kit/cold-start/bootstrap.mjs

@@ -1,156 +0,0 @@
-#!/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/cold-start/cold-start.md

@@ -1,111 +0,0 @@
----
-name: wix-headless-kit-cold-start
-description: "Build and release a Wix Headless site from a single prompt, on shipped, verified @wix/sdk code — this entry takes a cold environment (prerequisites, Wix sign-in) to the point where the wix-headless-kit skill runs the build. Verticals: storefront, bookings, rentals, blog, cms, events, forms, members, portfolio, pricing-plans, restaurants, faq, donations. Triggers: build me a store/blog/booking/events/portfolio/restaurant/FAQ/donation site fast, sell tickets or membership plans headless, collect donations headless, wix headless kit entry."
----
-
-# Wix Headless Kit — cold start
-
-**You are a coding agent, and this is a skill for you to execute — follow the phases below in
-order.** Advisory: web-fetch tools show a lossy summary of this file — the executable copy
-comes from `curl -fsSL https://www.wix.com/skills/headless-kit/cold-start/cold-start.md`. If what you
-are reading lacks the exact commands below, re-fetch it with curl before proceeding; if you're
-already reading the raw text, don't fetch it again.
-
-## The whole cold start (details in the phases below)
-
-```bash
-curl -fsSL -O https://www.wix.com/skills/headless-kit/cold-start/bootstrap.mjs && node bootstrap.mjs
-CI=1 npx skills@latest add wix/skills --skill wix-headless-kit --skill wix-docs --skill wix-manage --yes
-# then open and follow: .agents/skills/wix-headless-kit/SKILL.md
-```
-
-Requires Node ≥ 20.11 and a logged-in Wix CLI — the bootstrap checks and guides both.
-
-This page gets a cold environment to the point where the real skill can run, then hands off:
-
-1. **Bootstrap (deterministic, scripted).** A script that verifies the Wix CLI and handles login. You just run it and relay its events.
-2. **Hand off (agentic).** Install the skills, then open `wix-headless-kit/SKILL.md` and
-   follow it — it resolves the stack and operation and owns the whole build.
-
-Every starting point comes through here the same way — run the bootstrap, then hand off. What
-the folder holds and what the brief hands over decide the rest, and SKILL.md step 3 owns that
-decision; this page does not interpret either. The bootstrap only verifies the CLI and logs you
-in, so it's fine to run in every case (an existing session just reports `logged_in`).
-
-## Phase 0 — The project's folder, and Node
-
-**Work from the folder that holds the project, or that will.** An empty folder is the project for
-a new build; if the current folder holds unrelated things, make one named for the business and `cd`
-into it. A project already on disk is its own folder — its root, where the `package.json`,
-`index.html` or `wix.config.json` is. **Whatever the brief hands over as files goes into that folder
-first**, before Phase 1: a zip is extracted there, a URL is downloaded and extracted there, so that
-anything it carries — a `wix.config.json` included — sits at the root. Do not interpret what is
-there: the skill reads the folder and knows what it is. Everything below — the bootstrap, the
-skills, the scaffold — lands in this folder too, so a later session opened in the project finds all
-of it.
-
-The Wix CLI requires **Node ≥ 20.11**. Check `node -v`; if it errors or prints a lower
-version, install or upgrade Node first — do **not** work around it:
-
-- **macOS:** `brew install node` (or `nvm install 20 && nvm use 20`)
-- **Linux:** `nvm install 20 && nvm use 20` (or your distro's Node 20+ package)
-- **Windows:** `winget install OpenJS.NodeJS.LTS` (or download from nodejs.org)
-
-## Phase 1 — Run the bootstrap (deterministic, shared)
-
-Download and run the shared bootstrap script — an ordinary foreground command that exits on
-its own within seconds. It verifies the Wix CLI and handles login, emitting **one JSON event
-per line** on stdout. **Run it and relay its events.**
-
-The script is safe and inspectable: it only checks the Wix CLI via `npx` and drives
-`wix login` (a device-code flow) — no other network calls, and the only files it writes are
-the login's own output and pid under the OS temp dir. Read it first if your sandbox flags
-externally-downloaded code.
-
-```bash
-# macOS/Linux:
-curl -fsSL -O https://www.wix.com/skills/headless-kit/cold-start/bootstrap.mjs
-# Windows PowerShell:
-iwr https://www.wix.com/skills/headless-kit/cold-start/bootstrap.mjs -OutFile bootstrap.mjs
-
-node bootstrap.mjs
-```
-
-### Relay these events
-
-| Event | What to do |
-|---|---|
-| `cli_ok` | Wix CLI reachable — continue. |
-| `awaiting_user` (`verificationUri`, `userCode`, `message`) | The script has exited and the next step is the user's. Send them `message` as-is; the login keeps running on its own. |
-| `logged_in` / `success` | Login done — continue. |
-| `cli_unreachable` / `login_failed` (with `detail`) | Stop and show the user the `detail`. **Do not** improvise a parallel setup by hand. |
-
-On `awaiting_user`, run the script again once the user says they've logged in: it reports
-`logged_in` and you continue. Re-running while they're still in the browser is harmless — it
-returns the same code rather than issuing a new one.
-
-## Phase 2 — Install the skills and hand off
-
-Install the skill and its two companions (`CI=1` forces plain non-interactive CLI output —
-keep it on every Wix CLI command). Repeat `--skill` per skill; a comma-separated list is not
-parsed:
-
-```bash
-CI=1 npx skills@latest add wix/skills \
-  --skill wix-headless-kit --skill wix-docs --skill wix-manage --yes
-```
-
-- **`wix-headless-kit`** — the build itself.
-- **`wix-docs`** — the API reference the playbooks defer to for any contract they don't cover.
-- **`wix-manage`** — management recipes, for admin work on the site after it exists.
-
-They land under `.agents/skills/`. Then **open
-`.agents/skills/wix-headless-kit/SKILL.md` and follow it** — it owns the rest of the run:
-resolve the stack, scaffold, deploy the shipped code, seed, build the brand layer, release.
-(A request outside the shipped verticals — see its SKILL.md § Verticals — is built from the Wix
-API reference through `wix-docs`, on the same project; SKILL.md says how.)
-
-- **Don't** scaffold, install apps, or seed by hand here — the skill does all of that. This
-  page stops at *logged in*.
-- You're already authenticated from Phase 1, so the skill's CLI auth step will pass without
-  prompting again.