@wix/agent-skills 1.21.0 → 1.22.0

package/skills/wix-headless-fast/references/shared/seed/images.mjs

@@ -1,145 +0,0 @@
-// Shared seed util: entity images by URL or by AI GENERATION (Wix AI / Runware via the
-// wixapis proxy). BUILD-TIME only — imported by the vertical seed scripts, never shipped.
-//
-// The contract every seed relies on:
-//   - RESILIENT: nothing here ever throws out of resolveItemImages — a failed image resolves
-//     to null and the entity stays text-only; the seed's exit code never depends on images.
-//   - PARALLEL: all images resolve in one concurrent wave (each generation is its own
-//     single-task request — the google model 504s when one body bundles ≥3 tasks).
-//   - PASS-2: seeds create entities first, then attach what this returns — an image is never
-//     a precondition for an entity.
-//
-// Generation costs 1 Wix AI credit per image, billed to the account behind the site.
-// Authoritative reference: wix-headless/references/IMAGE_GENERATION.md.
-import { randomUUID } from "node:crypto";
-import { readFileSync } from "node:fs";
-import { basename, extname } from "node:path";
-
-const API = "https://www.wixapis.com";
-// Order = cheap-and-permissive first (runware ~0.009 credits/img, ~5s, loosest content
-// filter), then google (best fidelity, ~0.14, ~25s; rejects steps/CFGScale and free-form
-// sizes), then bfl (strictest filter — refuses trademark-ish prompts). A refusal or failure
-// falls through to the next model.
-const MODELS = ["runware:400@1", "google:4@2", "bfl:5@1"];
-/** Allowed dimensions: 1024×1024 (square — entities), 1376×768 (16:9 hero), 1200×896 (4:3). */
-export const IMAGE_SIZES = { square: [1024, 1024], hero: [1376, 768], editorial: [1200, 896] };
-
-async function req(ctx, path, body, timeoutMs = 45_000) {
-  const res = await fetch(API + path, {
-    method: "POST",
-    headers: {
-      Authorization: `Bearer ${ctx.token}`,
-      "wix-site-id": ctx.siteId,
-      "Content-Type": "application/json",
-    },
-    body: JSON.stringify(body),
-    signal: AbortSignal.timeout(timeoutMs),
-  });
-  const json = await res.json().catch(() => ({}));
-  if (!res.ok) throw new Error(`POST ${path} -> ${res.status}: ${JSON.stringify(json).slice(0, 300)}`);
-  return json;
-}
-
-/**
- * Generate one image; returns its short-lived URL (import it immediately). Tries each model
- * once — a per-model failure (bad params, 5xx, credit exhaustion, timeout) falls through to
- * the next; throws only after all models failed.
- * docs: no public reference for /runwareschemaless/v1/request — see wix-headless/references/IMAGE_GENERATION.md
- */
-export async function generateImage(ctx, prompt, { width = 1024, height = 1024 } = {}) {
-  let lastErr;
-  for (const model of MODELS) {
-    try {
-      const r = await req(ctx, "/runwareschemaless/v1/request", [
-        {
-          taskType: "imageInference",
-          taskUUID: randomUUID(), // must be a real UUIDv4 — slugs 400
-          outputType: "URL",
-          outputFormat: "PNG",
-          positivePrompt: prompt,
-          width,
-          height,
-          model,
-          numberResults: 1,
-        },
-      ]);
-      const url = r?.data?.[0]?.imageURL;
-      if (url) return url;
-      lastErr = new Error(`no imageURL in response: ${JSON.stringify(r).slice(0, 200)}`);
-    } catch (e) {
-      lastErr = e;
-    }
-  }
-  throw lastErr;
-}
-
-const MIME = { ".png": "image/png", ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".webp": "image/webp", ".gif": "image/gif", ".avif": "image/avif" };
-
-/**
- * Upload a LOCAL file (a path on this machine — the user's own asset) into Wix Media;
- * returns { id, url } (permanent). Two steps per the Upload API: generate-upload-url, then
- * PUT the bytes to it — the PUT response carries the file descriptor.
- * docs: https://dev.wix.com/docs/api-reference/assets/media/media-manager/files/generate-file-upload-url.md
- */
-export async function uploadImage(ctx, path, displayName) {
-  const ext = extname(path).toLowerCase();
-  const mimeType = MIME[ext];
-  if (!mimeType) throw new Error(`unsupported image extension: ${path}`);
-  const bytes = readFileSync(path); // throws loud on a wrong path (caught per-item by resolveItemImages)
-  // fileName's extension MUST match the real file type — a mismatch (slug.png for a .jpg) is
-  // rejected; keep the caller's display name, swap in the file's own extension.
-  const fileName = (displayName ?? basename(path)).replace(/\.[a-z0-9]+$/i, "") + ext;
-  const { uploadUrl } = await req(ctx, "/site-media/v1/files/generate-upload-url", {
-    mimeType,
-    fileName,
-  });
-  const res = await fetch(uploadUrl, {
-    method: "PUT",
-    headers: { "Content-Type": mimeType },
-    body: bytes,
-    signal: AbortSignal.timeout(120_000),
-  });
-  const json = await res.json().catch(() => ({}));
-  const f = json.file || json;
-  if (!res.ok || !f?.id) throw new Error(`upload failed (${res.status}): ${JSON.stringify(json).slice(0, 200)}`);
-  return { id: f.id, url: f.url };
-}
-
-/** Import an external/generated URL into Wix Media; returns { id, url } (permanent). */
-// docs: https://dev.wix.com/docs/api-reference/assets/media/media-manager/files/import-file.md
-export async function importImage(ctx, url, displayName = "image.png") {
-  const r = await req(ctx, "/site-media/v1/files/import", { url, mimeType: "image/png", displayName });
-  const f = r.file || r;
-  if (!f?.id) throw new Error(`import-file returned no file id: ${JSON.stringify(r).slice(0, 200)}`);
-  return { id: f.id, url: f.url };
-}
-
-/**
- * THE seed entry point. Resolves a batch of image specs to Wix Media files in ONE parallel
- * wave. Each spec: { path } (LOCAL file — the user's own asset, uploaded) OR { url }
- * (verified external URL — imported) OR { prompt } (generated, ~1 credit) — plus optional
- * displayName, width, height. Returns an array aligned with the input: { id, url } per
- * success, null per failure or empty spec. Never throws.
- */
-export async function resolveItemImages(ctx, specs, { perImageBudgetMs = 120_000 } = {}) {
-  // unref: the budget timer must never keep the seed process alive after the work is done —
-  // a lingering timer delays the seed's exit (and the run's .seed-exit marker) by the budget.
-  const deadline = new Promise((r) => {
-    const t = setTimeout(() => r(null), perImageBudgetMs);
-    t.unref?.();
-  });
-  const results = await Promise.allSettled(
-    (specs ?? []).map(async (s) => {
-      if (!s || (!s.path && !s.url && !s.prompt)) return null;
-      const resolve = (async () => {
-        if (s.path) return uploadImage(ctx, s.path, s.displayName);
-        const source = s.url ?? (await generateImage(ctx, s.prompt, { width: s.width, height: s.height }));
-        return importImage(ctx, source, s.displayName ?? "image.png");
-      })();
-      // Hard per-image budget: even a pathological multi-model hang costs the seed at most
-      // perImageBudgetMs of wall clock (the wave is parallel, so it's paid once, not per item).
-      return Promise.race([resolve, deadline]);
-    }),
-  );
-  return results.map((r) => (r.status === "fulfilled" ? r.value : null));
-}

package/skills/wix-headless-fast/references/shared/seed/read-site.mjs

@@ -1,99 +0,0 @@
-// The shared runner behind every vertical's `seed/read-site.mjs` — the build-time read of what a
-// site holds, so the agent sizes the content without composing a single Wix request.
-//
-//   node <SKILL_ROOT>/references/<vertical>/seed/read-site.mjs [--site <siteId>] [--limit <n>]
-//
-// The site is `--site`, else the `siteId` in ./wix.config.json. The token is minted by the Wix CLI
-// inside this process and never written anywhere. Output is ONE JSON object on stdout:
-//   { vertical, siteId, installed, ...what the vertical reads..., calls: [{ method, path, status, docs }] }
-// `calls` lists every request made, with the method's documentation URL — open one of those (the
-// URL plus `.md` is the full page) when the brief needs more than the summary shows. A failed call
-// is reported in `calls` with its status and message; the reader continues and marks the field null.
-import { execFileSync } from "node:child_process";
-import { readFileSync, existsSync } from "node:fs";
-
-const API = "https://www.wixapis.com";
-const DOCS_INSTALLED_APPS = "https://dev.wix.com/docs/api-reference/business-management/app-installation/app-installation/get-installed-apps";
-
-function flag(name) {
-  const i = process.argv.indexOf(`--${name}`);
-  return i !== -1 && process.argv[i + 1] && !process.argv[i + 1].startsWith("--") ? process.argv[i + 1] : null;
-}
-
-export function siteIdFromArgsOrConfig() {
-  const fromFlag = flag("site");
-  if (fromFlag) return fromFlag;
-  if (existsSync("wix.config.json")) {
-    const c = JSON.parse(readFileSync("wix.config.json", "utf8"));
-    return c.siteId ?? c.projectId ?? null;
-  }
-  return null;
-}
-
-export function makeApi(siteId) {
-  const token = execFileSync("npx", ["-y", "@wix/cli@latest", "token", "--site", siteId], { encoding: "utf8" }).trim();
-  if (!token) throw new Error("the Wix CLI returned no token — run `npx @wix/cli@latest login` first");
-  const calls = [];
-  async function call({ method = "POST", path, body, docs }) {
-    const entry = { method, path: path.split("?")[0], docs };
-    calls.push(entry);
-    const res = await fetch(API + path, {
-      method,
-      headers: { Authorization: token, "wix-site-id": siteId, "Content-Type": "application/json" },
-      body: body === undefined ? undefined : JSON.stringify(body),
-    });
-    const text = await res.text();
-    entry.status = res.status;
-    if (!res.ok) {
-      entry.error = text.slice(0, 200) || "(empty body)";
-      const e = new Error(`${method} ${entry.path} → ${res.status}: ${entry.error}`);
-      e.status = res.status;
-      throw e;
-    }
-    try { return text ? JSON.parse(text) : {}; } catch { return {}; }
-  }
-  // Same call, but a failure becomes null and stays in `calls` — for reads whose absence is data.
-  async function tryCall(opts) {
-    try { return await call(opts); } catch { return null; }
-  }
-  async function installed(appId) {
-    const r = await tryCall({ method: "GET", path: "/apps-installer-service/v1/app-instances", docs: DOCS_INSTALLED_APPS });
-    if (!r) return null;
-    return (r.appInstances ?? []).some((a) => a.appDefId === appId || a.appId === appId);
-  }
-  return { call, tryCall, installed, calls };
-}
-
-export const limit = () => Number(flag("limit") ?? 12);
-
-// read(api, { limit }) returns the vertical's summary; the runner adds the envelope and prints.
-export async function runReader({ vertical, appId, read }) {
-  const siteId = siteIdFromArgsOrConfig();
-  if (!siteId) {
-    console.log(JSON.stringify({ error: "no site: pass --site <siteId> or run in a folder with wix.config.json" }));
-    process.exit(1);
-  }
-  const api = makeApi(siteId);
-  const out = { vertical, siteId, scope: null };
-  out.installed = appId ? await api.installed(appId) : undefined;
-  let data = {};
-  if (out.installed === false) {
-    out.scope = `${vertical}: the app is not installed on this site — nothing to read; the vertical's seed installs it`;
-  } else {
-    try { data = await read(api, { limit: limit() }); }
-    catch (e) { out.error = String(e.message).slice(0, 300); }
-  }
-  // What this output is and is not: a SIZING. Every list is a sample page; the counts are the site.
-  const partial = Object.entries(data)
-    .filter(([k, v]) => Array.isArray(v) && typeof data[`${k.replace(/s$/, "")}Count`] === "number" && data[`${k.replace(/s$/, "")}Count`] > v.length)
-    .map(([k, v]) => `${k}: ${v.length} of ${data[`${k.replace(/s$/, "")}Count`]} shown`);
-  if (!out.scope) {
-    out.scope = "A sizing, not the content. Lists are one page (--limit, max 100); counts are the whole site. " +
-      (partial.length ? `Partial here: ${partial.join("; ")}. ` : "") +
-      "The pages read everything live through the deployed data layer. To read more or filter, page the same call: its method and documentation URL are in `calls`.";
-  }
-  Object.assign(out, data);
-  out.calls = api.calls;
-  out.docs = [...new Set(api.calls.map((c) => c.docs).filter(Boolean))];
-  console.log(JSON.stringify(out, null, 2));
-}