@wix/agent-skills 1.14.0 → 1.15.0

package/skills/wix-headless/scripts/plan-entity-image-waves.mjs

@@ -1,190 +0,0 @@
-#!/usr/bin/env node
-// Build a deterministic execution plan for Image Phase 2 from a slim image
-// agent's prompt array + the orchestrator's per-product / per-cms-item GETs.
-//
-// The slim image agent's only job is to return a list of brand-aligned prompts
-// (one per entity). This script transforms that list (plus the entity details
-// the orchestrator pre-fetched) into a structured plan the orchestrator can
-// execute as a sequence of concurrent batches:
-//
-//   waves     — Runware generation requests, grouped into waves of <waveSize>
-//               (default 3) to match the google:4@2 throttle. Each wave is
-//               one orchestration step with N parallel curls in one shell,
-//               backgrounded with `&`; each curl sends one task in the body array.
-//
-//   imports   — POST /site-media/v1/files/import requests, one per generated
-//               image. Indexed by taskUUID so the orchestrator threads the
-//               wave-result URL through to the import body.
-//
-//   patches   — Per-entity-type write requests (PATCH for products & blog
-//               posts; PUT for CMS items). Bodies use placeholders the
-//               orchestrator substitutes with import results:
-//                 __IMAGE_URL__       — the full wixstatic URL (file.url)
-//                 __IMAGE_FILE_ID__   — the file ID (file.fileUrl)
-//
-//   publishes — Re-publish calls for blog posts ONLY (PATCHing a published
-//               draft un-publishes it). One per blog-post entity.
-//
-// Usage:
-//   echo "$INPUT_JSON" | node plan-entity-image-waves.mjs
-//
-// The script is pure data transformation — no I/O beyond stdin / stdout, no
-// MCP, no network. The encoded knowledge is the per-entity-type body shapes
-// (frozen from references/images/INSTRUCTIONS.md so a single source of truth).
-
-import { readFileSync } from "node:fs";
-
-// Body shape constants — keep aligned with references/images/INSTRUCTIONS.md.
-const RUNWARE_DEFAULTS = {
-  taskType: "imageInference",
-  outputType: "URL",
-  outputFormat: "PNG",
-  model: "google:4@2",
-  numberResults: 1,
-};
-
-const DEFAULT_WAVE_SIZE = 3;
-
-let input;
-try {
-  input = JSON.parse(readFileSync(0, "utf8"));
-} catch (e) {
-  console.error(`plan-entity-image-waves: stdin is not valid JSON (${e.message})`);
-  process.exit(2);
-}
-
-const prompts = Array.isArray(input.prompts) ? input.prompts : [];
-if (prompts.length === 0) {
-  console.error("plan-entity-image-waves: no prompts in input — nothing to plan");
-  process.exit(2);
-}
-
-const productDetails = input.productDetails ?? {};
-const cmsDetails = input.cmsDetails ?? {};
-const waveSize = Math.max(1, Math.min(input.waveSize ?? DEFAULT_WAVE_SIZE, 8));
-const model = input.model ?? RUNWARE_DEFAULTS.model;
-
-// ---- 1. Runware waves (gen-side parallelism, throttle-bucketed) -----------
-const waves = [];
-for (let i = 0; i < prompts.length; i += waveSize) {
-  const slice = prompts.slice(i, i + waveSize);
-  waves.push(slice.map((p) => ({
-    taskUUID: p.taskUUID,
-    body: [{
-      ...RUNWARE_DEFAULTS,
-      model,
-      taskUUID: p.taskUUID,
-      positivePrompt: p.positivePrompt,
-      width: p.width ?? 1024,
-      height: p.height ?? 1024,
-      outputFormat: p.outputFormat ?? RUNWARE_DEFAULTS.outputFormat,
-    }],
-  })));
-}
-
-// ---- 2. Wix Media imports (one per generated image) -----------------------
-const imports = prompts.map((p) => ({
-  taskUUID: p.taskUUID,
-  mimeType: p.outputFormat === "JPG" ? "image/jpeg" : "image/png",
-  displayName: p.displayName ?? `${p.entityId}.${(p.outputFormat ?? "PNG").toLowerCase()}`,
-}));
-
-// ---- 3. Per-entity-type write requests ------------------------------------
-const patches = [];
-const publishes = [];
-
-for (const p of prompts) {
-  if (p.entityType === "product") {
-    const detail = productDetails[p.entityId];
-    if (!detail) {
-      console.error(`plan-entity-image-waves: missing productDetails for entityId=${p.entityId}`);
-      process.exit(1);
-    }
-    if (detail.revision === undefined || detail.revision === null) {
-      console.error(`plan-entity-image-waves: productDetails[${p.entityId}].revision is required (mandatory per Update-Product endpoint)`);
-      process.exit(1);
-    }
-    patches.push({
-      taskUUID: p.taskUUID,
-      entityType: "product",
-      entityId: p.entityId,
-      method: "PATCH",
-      url: `https://www.wixapis.com/stores/v3/products/${p.entityId}`,
-      // Body echoes options + variantsInfo (mandatory — see images/INSTRUCTIONS.md
-      // §428-prevention) and embeds the URL via __IMAGE_URL__ placeholder.
-      body: {
-        product: {
-          revision: detail.revision,
-          media: {
-            itemsInfo: {
-              items: [{ url: "__IMAGE_URL__", altText: p.displayName ?? p.entityId }],
-            },
-          },
-          ...(detail.options !== undefined ? { options: detail.options } : {}),
-          ...(detail.variantsInfo !== undefined ? { variantsInfo: detail.variantsInfo } : {}),
-        },
-      },
-    });
-  } else if (p.entityType === "blogPost") {
-    patches.push({
-      taskUUID: p.taskUUID,
-      entityType: "blogPost",
-      entityId: p.entityId,
-      method: "PATCH",
-      url: `https://www.wixapis.com/blog/v3/draft-posts/${p.entityId}`,
-      // Blog uses the file ID (fileUrl), not the wixstatic URL.
-      body: {
-        draftPost: {
-          media: { wixMedia: { image: { id: "__IMAGE_FILE_ID__" } } },
-        },
-      },
-    });
-    publishes.push({
-      entityId: p.entityId,
-      method: "POST",
-      url: `https://www.wixapis.com/blog/v3/draft-posts/${p.entityId}/publish`,
-    });
-  } else if (p.entityType === "cmsItem") {
-    const detail = cmsDetails[p.entityId];
-    if (!detail) {
-      console.error(`plan-entity-image-waves: missing cmsDetails for entityId=${p.entityId}`);
-      process.exit(1);
-    }
-    if (!detail.collectionId || !detail.imageField || !detail.data) {
-      console.error(`plan-entity-image-waves: cmsDetails[${p.entityId}] requires collectionId, imageField, and data (existing item record)`);
-      process.exit(1);
-    }
-    // Read-merge-PUT: echo every existing data field, set the image field
-    // to the placeholder URL. Echoing every existing field is what prevents wiping the rest of the record.
-    const mergedData = { ...detail.data, [detail.imageField]: "__IMAGE_URL__" };
-    patches.push({
-      taskUUID: p.taskUUID,
-      entityType: "cmsItem",
-      entityId: p.entityId,
-      method: "PUT",
-      url: `https://www.wixapis.com/wix-data/v2/items/${p.entityId}`,
-      body: {
-        dataCollectionId: detail.collectionId,
-        dataItem: { id: p.entityId, data: mergedData },
-      },
-    });
-  } else {
-    console.error(`plan-entity-image-waves: unknown entityType "${p.entityType}" for entityId=${p.entityId} — must be product | blogPost | cmsItem`);
-    process.exit(1);
-  }
-}
-
-const plan = {
-  meta: {
-    promptCount: prompts.length,
-    waveCount: waves.length,
-    waveSize,
-    model,
-  },
-  waves,
-  imports,
-  patches,
-  publishes,
-};
-
-console.log(JSON.stringify(plan, null, 2));

package/skills/wix-headless/scripts/scaffold.sh

@@ -1,139 +0,0 @@
-#!/usr/bin/env bash
-# Scaffold a new Wix Managed Headless project using the CLI's preset blank template.
-#
-# Usage:
-#   bash <SKILL_ROOT>/scripts/scaffold.sh <folder-name> "<Brand Name>" [--frontend astro|custom]
-#
-# <folder-name>:  lowercase letters, numbers, and hyphens only; must start with a
-#                 letter or number. The CLI scaffolds into a subdir of this name,
-#                 which this script then FLATTENS into the current directory (see
-#                 "In-place flatten" below) — so the project ends up *in CWD*, not
-#                 in a nested folder. The name is still required (the CLI mandates
-#                 it) but the local folder is transient.
-# <Brand Name>:   human-readable business name; quote if it contains spaces. The
-#                 CLI derives the Wix project display-name and URL slug from it, so
-#                 it must include at least one English letter or number.
-# --frontend:     the frontend axis. Defaults to "astro" — the only supported (and
-#                 only scaffolded) frontend. "custom" (any non-astro frontend) is
-#                 NOT scaffolded yet: Discovery routes custom to the not-available
-#                 stub (references/custom/INSTRUCTIONS.md) before scaffold ever runs,
-#                 so this script should only ever be invoked with "astro". If it is
-#                 invoked with "custom" it exits 4 (recognized, not staged).
-#
-# After scaffold succeeds, the project lives in the CURRENT directory (the subdir
-# was flattened away). Read ./wix.config.json to extract appId (project's appId)
-# and siteId (used as --site for `wix token` and in REST call bodies). The
-# orchestrator does that read; this script runs the npm create + the flatten.
-#
-# Behavior:
-#   - Pre-flight validates the folder name syntax (regex ^[a-z0-9][a-z0-9-]*$).
-#   - Pre-flight requires both positional args.
-#   - Runs `npm create @wix/new@latest headless` with --no-publish + --skip-install
-#     so the orchestrator can deferred-install with its own package set.
-#   - Passes bare `--site-template` so non-interactive scaffolding stays on the
-#     blank starter. Without it, @wix/create-new (>=0.0.72) prompts for a template
-#     choice and aborts in a non-TTY agent shell ("not supported in non-interactive
-#     terminals").
-#   - FLATTENS the scaffolded subdir into CWD (single-folder layout: one `.wix`,
-#     CWD == project == site-root). Interim until the CLI supports in-place create.
-#
-# Exit codes:
-#   0 — ok
-#   2 — argument validation failed (bad folder name, missing args, unknown --frontend value)
-#   3 — Wix CLI not logged in (defensive; the Discovery pre-flight is the primary check)
-#   4 — frontend value recognized but not scaffolded yet (custom today)
-#   5 — scaffold succeeded but the subdir could not be flattened into CWD (name collision)
-#   <other> — npm create failed; stderr surfaced to caller for orchestrator-side
-#             recovery (auth / other scaffold failures live in the orchestrator).
-
-set -euo pipefail
-
-FRONTEND="astro"
-POSITIONAL=()
-while [[ $# -gt 0 ]]; do
-  case "$1" in
-    --frontend)
-      if [[ $# -lt 2 ]]; then
-        echo "scaffold.sh: --frontend requires a value (astro|custom)." >&2
-        exit 2
-      fi
-      FRONTEND="$2"
-      shift 2
-      ;;
-    --frontend=*)
-      FRONTEND="${1#--frontend=}"
-      shift
-      ;;
-    *)
-      POSITIONAL+=("$1")
-      shift
-      ;;
-  esac
-done
-
-if [[ ${#POSITIONAL[@]} -lt 2 || -z "${POSITIONAL[0]:-}" || -z "${POSITIONAL[1]:-}" ]]; then
-  echo "scaffold.sh: both positional args required. Got folder-name='${POSITIONAL[0]:-}' brand-name='${POSITIONAL[1]:-}'." >&2
-  echo "Usage: bash scaffold.sh <folder-name> \"<Brand Name>\" [--frontend astro|custom] — folder name first, brand quoted." >&2
-  exit 2
-fi
-
-case "$FRONTEND" in
-  astro)
-    ;;
-  custom)
-    echo "scaffold.sh: --frontend=custom is not scaffolded yet — astro is the only supported frontend." >&2
-    echo "Discovery routes custom (non-astro) frontends to references/custom/INSTRUCTIONS.md (the not-available stub) before scaffold; this script should not be invoked with 'custom'." >&2
-    exit 4
-    ;;
-  *)
-    echo "scaffold.sh: unknown --frontend value '$FRONTEND'. Allowed: astro, custom." >&2
-    exit 2
-    ;;
-esac
-
-if [[ ! "${POSITIONAL[0]}" =~ ^[a-z0-9][a-z0-9-]*$ ]]; then
-  echo "scaffold.sh: folder-name='${POSITIONAL[0]}' is not valid." >&2
-  echo "Folder name must contain only lowercase letters, numbers, and hyphens, and start with a letter or number." >&2
-  echo "Derive it from the brand as a lowercase, npm-safe directory name." >&2
-  exit 2
-fi
-
-# Defensive auth check — DISCOVERY.md's pre-flight should have caught this
-# already, but scaffold.sh is also a documented standalone entry point
-# (SKILL.md § "When NOT to use this skill"). `npm create @wix/new` requires
-# an active CLI session and otherwise fails mid-run with an opaque error.
-# `wix whoami` exits non-zero on a logged-out session and prints the
-# authenticated email + user id when logged in.
-if ! npx @wix/cli@latest whoami >/dev/null 2>&1; then
-  echo "scaffold.sh: not logged in to Wix CLI." >&2
-  echo "Run 'npx @wix/cli@latest login' and retry." >&2
-  exit 3
-fi
-
-FOLDER="${POSITIONAL[0]}"
-
-npm create @wix/new@latest headless -- \
-  --business-name "${POSITIONAL[1]}" \
-  --folder-name "$FOLDER" \
-  --site-template \
-  --no-publish \
-  --skip-install
-
-# --- In-place flatten (interim hack) -----------------------------------------
-# The CLI always scaffolds into a named subdir; there is NO in-place option —
-# `headless init` regex-rejects `--folder-name .` ("must contain only lowercase
-# letters, numbers, and hyphens") and offers no --cwd/--here flag. To keep the
-# whole run single-folder (one `.wix`, CWD == project == site-root, no nested
-# `.wix` to reason about), fold the scaffolded subdir up into the current dir.
-#
-# The .wix-merge + mv -n + rmdir logic is identical to flatten.sh (the own-build
-# path's framework-agnostic flatten), so we delegate to it rather than duplicate.
-# flatten.sh lives next to this script; resolve its path relative to our own dir
-# so the call works regardless of CWD. (Both exit 5 on the same name-collision.)
-# When the CLI gains `--folder-name .` (or --cwd), the TODO to drop the flatten
-# lives in flatten.sh.
-if [[ -d "$FOLDER" ]]; then
-  SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-  bash "$SCRIPT_DIR/flatten.sh" "$FOLDER"
-fi
-# -----------------------------------------------------------------------------

package/skills/wix-headless/scripts/seed-utilities.sh

@@ -1,93 +0,0 @@
-#!/usr/bin/env bash
-# Frontend-track project prep: copy the skill's shared utilities into the
-# project's src/utils/ and strip the Astro starter cruft that ships with the
-# blank template. This is local-project (frontend) work, not backend seeding —
-# the orchestrator only runs it in scaffold mode (integrate mode has no
-# skill-written frontend to prep, so it is never invoked there).
-#
-# Usage (both modes work):
-#   bash <SKILL_ROOT>/scripts/seed-utilities.sh --template astro
-#   bash <(curl -s https://dev.wix.com/skills/wix-headless/scripts/seed-utilities.sh) --template astro
-#
-# --template (optional, default astro): astro
-#   Astro is the only frontend the skill scaffolds and preps, so the value is
-#   always "astro". Custom (non-astro) frontends route to the not-available stub
-#   (references/custom/INSTRUCTIONS.md) and never reach this script.
-#
-# Run from the project directory (CWD = <scaffold>/). The script auto-detects
-# whether shared-utilities is available on disk (tgz install) and falls back
-# to fetching from the well-known URL when streamed via process substitution
-# (BASH_SOURCE is /dev/fd/N, so the on-disk lookup naturally falls through).
-#
-# Behavior:
-#   - Copies the three shared utility files into src/utils/ for both templates —
-#     never overwrites an existing file (users can drop in their own version).
-#   - On --template=astro, removes Astro starter cruft (Welcome.astro + marketing
-#     SVGs) that ships with the blank template but is never imported by the build
-#     skill.
-#
-# Shared utilities copied:
-#   - wix-image.ts  — media URL resolver (used by stores, blog, cms)
-#   - analytics.ts  — event tracking (used by stores, ecom, blog)
-#   - ricos.ts      — Ricos JSON to HTML renderer for SSR Astro pages
-
-set -euo pipefail
-
-SKILL_URL="https://dev.wix.com/skills/wix-headless"
-UTILS=(analytics.ts ricos.ts wix-image.ts)
-
-TEMPLATE="astro"
-while [[ $# -gt 0 ]]; do
-  case "$1" in
-    --template)
-      TEMPLATE="$2"
-      shift 2
-      ;;
-    --template=*)
-      TEMPLATE="${1#--template=}"
-      shift
-      ;;
-    *)
-      echo "seed-utilities.sh: unexpected arg: $1" >&2
-      exit 2
-      ;;
-  esac
-done
-
-case "$TEMPLATE" in
-  astro) ;;
-  *)
-    echo "seed-utilities.sh: --template must be 'astro' (the only supported frontend); got $TEMPLATE" >&2
-    echo "(Custom non-astro frontends route to the stub and never reach this script.)" >&2
-    exit 2
-    ;;
-esac
-
-# Mode detection: prefer on-disk skill root if the sibling dir exists, else
-# fetch over HTTP. Covers both tgz install and `bash <(curl ...)` streaming.
-SHARED_UTILS_DIR=""
-script_path="${BASH_SOURCE[0]}"
-if [[ -f "$script_path" ]]; then
-  candidate="$(dirname "$script_path")/../shared-utilities"
-  if [[ -d "$candidate" ]]; then
-    SHARED_UTILS_DIR="$(cd "$candidate" && pwd)"
-  fi
-fi
-
-mkdir -p src/utils
-
-for f in "${UTILS[@]}"; do
-  dest="src/utils/$f"
-  if [[ -e "$dest" ]]; then continue; fi
-  if [[ -n "$SHARED_UTILS_DIR" ]]; then
-    cp "$SHARED_UTILS_DIR/$f" "$dest"
-  else
-    curl -fsSL "$SKILL_URL/shared-utilities/$f" -o "$dest"
-  fi
-done
-
-# Astro starter cruft cleanup — astro template only.
-if [[ "$TEMPLATE" == "astro" ]]; then
-  rm -f src/components/Welcome.astro
-  rm -f src/assets/astro.svg src/assets/wix.svg src/assets/background.svg
-fi

package/skills/wix-headless/scripts/write-decorative-json.mjs

@@ -1,62 +0,0 @@
-#!/usr/bin/env node
-// Write the decorative slot→URL map to src/decorative-images.json for a
-// framework-SPA (`own`) frontend. This is the `own`-branch analog of
-// patch-decorative-slots.mjs (which injects <img> into .astro source) — but
-// instead of patching framework source, the generated SPA *imports* this JSON
-// and its hero/about components read it, with a themed-block fallback when a
-// slot is empty/absent. This avoids fragile JSX/Vue/Svelte string-patching and
-// mirrors how the SPA already imports .wix/design-tokens.css.
-//
-// It is called twice in the `own` flow (BUILD-own-build.md):
-//   1. At bootstrap, with EMPTY stdin → writes `{}` (placeholder), so the app
-//      builds + renders themed blocks even if Image Phase 1 never runs.
-//   2. At the seed gate (ai-generated only), with Image Phase 1's data.slots
-//      piped in → OVERWRITES the file with the real URLs. This MUST happen
-//      before `npm run build` (Vite resolves the JSON import at build time).
-//
-// Writes to src/decorative-images.json (inside the Vite root, so it is always
-// importable — unlike .wix/, which may sit outside the bundler root).
-//
-// Usage:
-//   echo '{"hero":"https://...","about":"https://..."}' \
-//     | node write-decorative-json.mjs <project-dir>
-//   : | node write-decorative-json.mjs <project-dir>     # placeholder {}
-
-import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
-import { join } from "node:path";
-
-const projectDir = process.argv[2] ?? process.cwd();
-
-let slots = {};
-if (!process.stdin.isTTY) {
-  const raw = readFileSync(0, "utf8").trim();
-  if (raw) {
-    try {
-      slots = JSON.parse(raw);
-    } catch (e) {
-      console.error(JSON.stringify({ status: "error", reason: `stdin is not valid JSON (${e.message})` }));
-      process.exit(2);
-    }
-    if (!slots || typeof slots !== "object" || Array.isArray(slots)) {
-      console.error(JSON.stringify({ status: "error", reason: "expected a JSON object mapping slot keys to URLs" }));
-      process.exit(2);
-    }
-  }
-}
-
-// Drop empty/falsy URLs so the component's themed-block fallback kicks in.
-const clean = {};
-for (const [k, v] of Object.entries(slots)) {
-  if (typeof v === "string" && v.trim()) clean[k] = v.trim();
-}
-
-const srcDir = join(projectDir, "src");
-mkdirSync(srcDir, { recursive: true });
-const dest = join(srcDir, "decorative-images.json");
-writeFileSync(dest, JSON.stringify(clean, null, 2) + "\n");
-
-console.log(JSON.stringify({
-  status: Object.keys(clean).length ? "ok" : "placeholder",
-  file: dest,
-  slots: Object.keys(clean),
-}, null, 2));

package/skills/wix-headless/shared-utilities/analytics.ts

@@ -1,40 +0,0 @@
-export type AnalyticsEventName =
-  | "AddToCart"
-  | "RemoveFromCart"
-  | "InitiateCheckout"
-  | "Purchase"
-  | "ArticleView"
-  | "FormSubmit"
-  | "AddProductImpression"
-  | "ViewContent"
-  | "ClickProduct"
-  | (string & {});
-
-export function trackEvent(
-  name: AnalyticsEventName,
-  payload?: Record<string, unknown>,
-): void {
-  if (typeof window === "undefined") return;
-
-  const event = { name, ...(payload ?? {}) };
-
-  const w = window as unknown as {
-    dataLayer?: unknown[];
-    wixAnalytics?: { track(event: { name: string } & Record<string, unknown>): void };
-  };
-
-  if (w.wixAnalytics?.track) {
-    w.wixAnalytics.track(event);
-    return;
-  }
-
-  if (w.dataLayer) {
-    w.dataLayer.push({ event: name, ...event });
-    return;
-  }
-
-  const meta = import.meta as unknown as { env?: { DEV?: boolean } };
-  if (meta.env?.DEV) {
-    console.debug("[analytics]", event);
-  }
-}