@wix/agent-skills 1.0.0

package/skills/wix-headless/scripts/check-manifest.mjs

@@ -0,0 +1,198 @@
+#!/usr/bin/env node
+// Post-phase manifest check + template-copy recovery.
+//
+// Verifies that every file declared in each loaded pack's `creates:` array
+// for the named phase exists on disk. If a file is missing, attempts to
+// recover by copying the canonical template from <SKILL_ROOT>/templates/<pack>/.
+// Outputs a JSON summary of present / recovered / errored files.
+//
+// Usage (both modes work):
+//   node <SKILL_ROOT>/scripts/check-manifest.mjs <project-dir> <phase> <packs-csv>
+//   curl -s https://dev.wix.com/skills/wix-headless/scripts/check-manifest.mjs \
+//     | node --input-type=module - <project-dir> <phase> <packs-csv>
+//
+//   <phase> ∈ { "components", "pages" }
+//   <packs-csv> = comma-separated pack names (loaded verticals), e.g. "stores,ecom,cms"
+//
+// Note: `node <(curl ...)` does NOT work for .mjs files — Node sees /dev/fd/N
+// with no extension and rejects ESM syntax. Use the stdin form above.
+//
+// Skill-local file reads (vertical pack markdowns, template files) auto-detect
+// whether they can resolve on disk (tgz install) and fall back to HTTP fetch
+// otherwise (stream via stdin).
+//
+// Behavior:
+//   - For each pack, parses `references/verticals/<pack>.md` to extract the
+//     `creates:` array.
+//   - For each `creates:` entry where phase matches:
+//       * If file exists in the project → "present"
+//       * If missing AND a template exists at `templates/<pack>/<tail>`
+//         (where <tail> is the path under src/pages/ for page files, or the
+//         basename for everything else) → copy/fetch it; record as "recovered".
+//       * Otherwise → record as "missing" with a remediation hint.
+//   - Exit 0 on happy path or recoverable misses.
+//   - Exit 1 if any file is unrecoverably missing.
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync, copyFileSync } from "node:fs";
+import { join, dirname, basename, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const SKILL_URL = "https://dev.wix.com/skills/wix-headless";
+
+// Mode detection: prefer on-disk skill root if reachable, else use HTTP.
+// When invoked as `node <(curl ...)`, import.meta.url is `file:///dev/fd/N`
+// and the candidate root won't contain `references/verticals` — so we fall
+// through to URL mode automatically.
+let SKILL_ROOT_DISK = null;
+try {
+  const scriptDir = dirname(fileURLToPath(import.meta.url));
+  const candidate = resolve(scriptDir, "..");
+  if (existsSync(join(candidate, "references/verticals"))) {
+    SKILL_ROOT_DISK = candidate;
+  }
+} catch {
+  // fileURLToPath may fail on non-file URLs; fall through to URL mode.
+}
+
+// Read a skill-local file (relative path like "references/verticals/stores.md").
+// Returns null when the file doesn't exist.
+async function readSkillText(relPath) {
+  if (SKILL_ROOT_DISK) {
+    const p = join(SKILL_ROOT_DISK, relPath);
+    if (!existsSync(p)) return null;
+    return readFileSync(p, "utf8");
+  }
+  const url = `${SKILL_URL}/${relPath}`;
+  const r = await fetch(url);
+  if (r.status === 404) return null;
+  if (!r.ok) throw new Error(`fetch ${url}: HTTP ${r.status}`);
+  return await r.text();
+}
+
+// Copy a skill-local file at relPath into destPath (in the user's project).
+// Returns true on success, false if the source doesn't exist.
+async function copySkillFile(relPath, destPath) {
+  if (SKILL_ROOT_DISK) {
+    const src = join(SKILL_ROOT_DISK, relPath);
+    if (!existsSync(src)) return false;
+    mkdirSync(dirname(destPath), { recursive: true });
+    copyFileSync(src, destPath);
+    return true;
+  }
+  const text = await readSkillText(relPath);
+  if (text === null) return false;
+  mkdirSync(dirname(destPath), { recursive: true });
+  writeFileSync(destPath, text);
+  return true;
+}
+
+const [, , projectDir, phase, packsCsv] = process.argv;
+
+if (!projectDir || !phase || !packsCsv) {
+  console.error("usage: check-manifest.mjs <project-dir> <phase> <packs-csv>");
+  process.exit(2);
+}
+
+if (phase !== "components" && phase !== "pages") {
+  console.error(`check-manifest: invalid phase "${phase}" — must be "components" or "pages"`);
+  process.exit(2);
+}
+
+const packs = packsCsv.split(",").map((p) => p.trim()).filter(Boolean);
+
+// Map a `creates:` file path to its template path (relative to skill root).
+// Heuristic: `src/pages/<X>` preserves <X> under templates/<pack>/; everything
+// else uses basename only.
+function templateRelPath(packName, srcPath) {
+  const pagesMatch = srcPath.match(/^src\/pages\/(.+)$/);
+  const tail = pagesMatch ? pagesMatch[1] : basename(srcPath);
+  return `templates/${packName}/${tail}`;
+}
+
+// Parse `creates:` block from a vertical pack's markdown frontmatter.
+// Format (one per line):
+//   - { file: src/utils/back-in-stock.ts,          phase: components }
+function parseCreates(text) {
+  const lines = text.split("\n");
+  const entries = [];
+  let inCreates = false;
+  for (const line of lines) {
+    if (/^creates:\s*$/.test(line)) {
+      inCreates = true;
+      continue;
+    }
+    if (inCreates) {
+      // Block ends at a non-indented, non-blank line that doesn't start with `-`.
+      if (/^[^\s-]/.test(line)) {
+        inCreates = false;
+        continue;
+      }
+      const m = line.match(/^\s*-\s*\{\s*file:\s*([^,]+?),\s*phase:\s*([\w-]+)\s*\}/);
+      if (m) entries.push({ file: m[1].trim(), phase: m[2].trim() });
+    }
+  }
+  return entries;
+}
+
+const present = [];
+const recovered = [];
+const missing = [];
+
+for (const pack of packs) {
+  const verticalRel = `references/verticals/${pack}.md`;
+  const text = await readSkillText(verticalRel);
+  if (text === null) {
+    missing.push({
+      pack,
+      path: null,
+      code: "PACK_NOT_FOUND",
+      remediation: `vertical pack file not found at ${verticalRel} — pack "${pack}" may not be a valid loaded vertical`,
+    });
+    continue;
+  }
+
+  const entries = parseCreates(text).filter((e) => e.phase === phase);
+
+  for (const { file } of entries) {
+    const destPath = join(projectDir, file);
+    if (existsSync(destPath)) {
+      present.push({ pack, path: file });
+      continue;
+    }
+
+    const templateRel = templateRelPath(pack, file);
+    const ok = await copySkillFile(templateRel, destPath);
+    if (ok) {
+      recovered.push({
+        pack,
+        path: file,
+        source: "template-copy",
+        template: templateRel,
+      });
+      continue;
+    }
+
+    missing.push({
+      pack,
+      path: file,
+      code: "PHASE_FILE_MISSING",
+      remediation: `the ${pack} agent did not write this file and the pack ships no template at ${templateRel}. Re-dispatch the ${phase} scope, or report the gap to the pack maintainer.`,
+    });
+  }
+}
+
+const summary = {
+  phase,
+  packs,
+  counts: {
+    present: present.length,
+    recovered: recovered.length,
+    missing: missing.length,
+  },
+  present,
+  recovered,
+  missing,
+};
+console.log(JSON.stringify(summary, null, 2));
+
+process.exit(missing.length > 0 ? 1 : 0);

package/skills/wix-headless/scripts/copy-utility-templates.mjs

@@ -0,0 +1,153 @@
+#!/usr/bin/env node
+// Copy templated utility files into the project for the named phase.
+// Invoked by the wix-headless skill orchestrator before Phase 3 Components or
+// Phase 4 Pages dispatches, so that mechanical SDK-wrapper utilities
+// (back-in-stock.ts, discounts.ts, categories.ts) are on disk by the time
+// agents start.
+//
+// These files are pure templates — same shape regardless of brand. Letting an
+// LLM regenerate them costs tokens and risks drift. Pre-copying is structurally
+// better.
+//
+// Usage (both modes work):
+//   node <SKILL_ROOT>/scripts/copy-utility-templates.mjs <project-dir> <phase>
+//   curl -s https://dev.wix.com/skills/wix-headless/scripts/copy-utility-templates.mjs \
+//     | node --input-type=module - <project-dir> <phase>
+//
+//   <phase> ∈ { "components", "pages" }
+//
+// Note: `node <(curl ...)` does NOT work for .mjs files — Node sees /dev/fd/N
+// with no extension and rejects ESM syntax. Use the stdin form above.
+//
+// Template files auto-detect whether they can be read on disk (tgz install)
+// and fall back to HTTP fetch when streamed via stdin.
+//
+// Reads `.wix/site.json` to discover which packs are loaded, then copies the
+// matching templates for the given phase. Never overwrites an existing file
+// (so user customisations and earlier orchestrator state are preserved).
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync, copyFileSync } from "node:fs";
+import { join, dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const SKILL_URL = "https://dev.wix.com/skills/wix-headless";
+
+// Mode detection — see check-manifest.mjs for the same pattern.
+let SKILL_ROOT_DISK = null;
+try {
+  const scriptDir = dirname(fileURLToPath(import.meta.url));
+  const candidate = resolve(scriptDir, "..");
+  if (existsSync(join(candidate, "templates"))) {
+    SKILL_ROOT_DISK = candidate;
+  }
+} catch {
+  // fileURLToPath may fail on non-file URLs; fall through to URL mode.
+}
+
+// Copy a template file (path relative to <SKILL_ROOT>/templates/) into the
+// project at destPath. Returns { ok: true } on success, or { ok: false,
+// reason: "..." } on failure (source missing, HTTP error, IO error).
+async function copyTemplate(sourceRel, destPath) {
+  if (SKILL_ROOT_DISK) {
+    const src = join(SKILL_ROOT_DISK, "templates", sourceRel);
+    if (!existsSync(src)) return { ok: false, reason: `missing on disk: ${src}` };
+    try {
+      mkdirSync(dirname(destPath), { recursive: true });
+      copyFileSync(src, destPath);
+      return { ok: true };
+    } catch (e) {
+      return { ok: false, reason: e.message };
+    }
+  }
+  const url = `${SKILL_URL}/templates/${sourceRel}`;
+  try {
+    const r = await fetch(url);
+    if (r.status === 404) return { ok: false, reason: `missing at ${url}` };
+    if (!r.ok) return { ok: false, reason: `fetch ${url}: HTTP ${r.status}` };
+    const text = await r.text();
+    mkdirSync(dirname(destPath), { recursive: true });
+    writeFileSync(destPath, text);
+    return { ok: true };
+  } catch (e) {
+    return { ok: false, reason: e.message };
+  }
+}
+
+// Hardcoded mapping: { pack, phase, source (relative to templates dir), dest (relative to project) }.
+// To add a new templated utility: ship the file under templates/<pack>/, then add
+// an entry here. Keep this list small — only files that are pure SDK wrappers
+// with no brand-specific content belong here.
+const TEMPLATES = [
+  { pack: "stores", phase: "components", source: "stores/back-in-stock.ts", dest: "src/utils/back-in-stock.ts" },
+  { pack: "ecom", phase: "components", source: "ecom/discounts.ts", dest: "src/utils/discounts.ts" },
+  { pack: "stores", phase: "pages", source: "stores/categories.ts", dest: "src/utils/categories.ts" },
+];
+
+const projectDir = process.argv[2];
+const phase = process.argv[3];
+
+if (!projectDir || !phase) {
+  console.error("usage: copy-utility-templates.mjs <project-dir> <phase>");
+  console.error("  <phase> ∈ { components, pages }");
+  process.exit(2);
+}
+
+if (phase !== "components" && phase !== "pages") {
+  console.error(`copy-utility-templates: invalid phase "${phase}" — must be "components" or "pages"`);
+  process.exit(2);
+}
+
+const sitePath = join(projectDir, ".wix/site.json");
+let loadedPacks;
+try {
+  const site = JSON.parse(readFileSync(sitePath, "utf8"));
+  loadedPacks = new Set(site.verticals ?? []);
+  if (loadedPacks.size === 0) {
+    console.error(`copy-utility-templates: site.json.verticals is empty — has Setup completed?`);
+    process.exit(1);
+  }
+} catch (e) {
+  console.error(`copy-utility-templates: cannot read ${sitePath} (${e.message}). Has Setup completed?`);
+  process.exit(1);
+}
+
+const candidates = TEMPLATES.filter((t) => t.phase === phase && loadedPacks.has(t.pack));
+
+if (candidates.length === 0) {
+  console.log(`copy-utility-templates: no templates for phase "${phase}" with loaded packs ${[...loadedPacks].join(", ")} — nothing to do`);
+  process.exit(0);
+}
+
+const copied = [];
+const skipped = [];
+const errors = [];
+
+for (const { pack, source, dest } of candidates) {
+  const destPath = join(projectDir, dest);
+
+  if (existsSync(destPath)) {
+    skipped.push(dest);
+    continue;
+  }
+
+  const result = await copyTemplate(source, destPath);
+  if (result.ok) {
+    copied.push(dest);
+  } else {
+    errors.push(`failed to copy ${source} → ${dest} (pack "${pack}"): ${result.reason}`);
+  }
+}
+
+const summary = {
+  phase,
+  packs: [...loadedPacks],
+  copied,
+  skipped,
+  errors,
+};
+
+console.log(JSON.stringify(summary, null, 2));
+
+if (errors.length > 0) {
+  process.exit(1);
+}

package/skills/wix-headless/scripts/emit-design-tokens.mjs

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+// Generate .wix/design-tokens.css and .wix/site.d.ts deterministically from
+// .wix/site.json.designTokens. Invoked by the wix-headless skill orchestrator
+// after the Phase 2 Design System agent's return is merged into site.json.
+//
+// Why a script (not agent work): both files are pure projections of the
+// designTokens JSON — no judgment, no brand-context dependence. An LLM
+// emitting them is wasted tokens AND a drift risk (malformed :root blocks,
+// missing token groups, divergent .d.ts skeletons).
+
+import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+
+const projectDir = process.argv[2] ?? process.cwd();
+const sitePath = join(projectDir, ".wix/site.json");
+
+let site;
+try {
+  site = JSON.parse(readFileSync(sitePath, "utf8"));
+} catch (e) {
+  console.error(`emit-design-tokens: cannot read ${sitePath} (${e.message}). Has Phase 2 Design System returned and merged?`);
+  process.exit(1);
+}
+
+const tokens = site.designTokens ?? {};
+if (!tokens || Object.keys(tokens).length === 0) {
+  console.error("emit-design-tokens: site.json.designTokens is empty — designer return not merged.");
+  process.exit(1);
+}
+
+const wixDir = join(projectDir, ".wix");
+mkdirSync(wixDir, { recursive: true });
+
+// .wix/design-tokens.css ----------------------------------------------------
+const PREFIX = {
+  colors: "--color-",
+  fonts: "--font-",
+  radii: "--radius-",
+  spacing: "--spacing-",
+};
+
+const cssLines = ["/* Generated from .wix/site.json.designTokens. Do not edit. */", ":root {"];
+for (const [group, prefix] of Object.entries(PREFIX)) {
+  const entries = tokens[group] ?? {};
+  for (const [key, value] of Object.entries(entries)) {
+    cssLines.push(`  ${prefix}${key}: ${value};`);
+  }
+}
+cssLines.push("}", "");
+writeFileSync(join(wixDir, "design-tokens.css"), cssLines.join("\n"));
+
+// .wix/site.d.ts ------------------------------------------------------------
+const typeFor = (group) => {
+  const keys = Object.keys(tokens[group] ?? {});
+  if (keys.length === 0) return "Record<string, string>";
+  const literal = keys.map((k) => JSON.stringify(k)).join(" | ");
+  return `Record<${literal}, string>`;
+};
+
+const dts = `// Generated from .wix/site.json.designTokens. Do not edit.
+export type Brand = { name: string; description: string };
+export type DesignTokens = {
+  colors: ${typeFor("colors")};
+  fonts: ${typeFor("fonts")};
+  radii: ${typeFor("radii")};
+  spacing: ${typeFor("spacing")};
+};
+export type Product = { id: string; name: string; slug: string; price: number; variantId: string };
+export declare const site: {
+  brand: Brand;
+  designTokens: DesignTokens;
+  seeded: { products?: Product[]; posts?: unknown[]; collections?: Record<string, unknown[]> };
+};
+`;
+writeFileSync(join(wixDir, "site.d.ts"), dts);
+
+console.log(`emit-design-tokens: wrote ${join(wixDir, "design-tokens.css")} and ${join(wixDir, "site.d.ts")}`);

package/skills/wix-headless/scripts/finalize-run-json.mjs

@@ -0,0 +1,141 @@
+#!/usr/bin/env node
+// Finalize and write .wix/run.json at the end of the build.
+//
+// The orchestrator collects agent returns, timings, and outcome data over the
+// run. This script takes the orchestrator's draft as a JSON blob via stdin,
+// runs the timing-completeness gate (every required phase MUST have non-null
+// seconds, otherwise emit MISSING_TIMING errors), computes totalSeconds from
+// started/ended, writes the canonical .wix/run.json, and prints the perf
+// one-liner the orchestrator shows in the final message.
+//
+// Usage:
+//   echo "$DRAFT_JSON" | node finalize-run-json.mjs <project-dir>
+//
+// Input shape (via stdin):
+//   {
+//     "run":   { started, ended, brand, prompt, verticals, packs },
+//     "outcome": { build, previewUrl, dashboardUrl, ... },
+//     "phases":  [ { phase, status, seconds, data?, errors? }, ... ],
+//     "recoveries": [ ... ],   // optional; from manifest-check script outputs
+//     "errors":     [ ... ],   // optional; from agent returns / orchestrator
+//     "notes":      [ ... ],   // optional
+//     "requiredPhases": ["scaffold","app-install-Wix Stores","env-pull",...]
+//   }
+//
+// `requiredPhases` is the orchestrator's set of skill-invoked phases that MUST
+// have a captured duration (scaffold, every app-install-*, env-pull,
+// seed-utilities, npm-install, build, release|preview, etc.). The set is
+// run-specific (number of app-install-* depends on loaded packs), so the
+// orchestrator passes it in rather than the script guessing.
+//
+// Output:
+//   - Writes .wix/run.json (full shape, with timing-completeness gate applied).
+//   - Prints to stdout: a JSON object with { perfLine, missingTiming, totalSeconds }.
+
+import { writeFileSync, mkdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+const projectDir = process.argv[2];
+
+if (!projectDir) {
+  console.error("usage: cat draft.json | finalize-run-json.mjs <project-dir>");
+  process.exit(2);
+}
+
+let draft;
+try {
+  draft = JSON.parse(readFileSync(0, "utf8"));
+} catch (e) {
+  console.error(`finalize-run-json: stdin is not valid JSON (${e.message})`);
+  process.exit(2);
+}
+
+const run = draft.run ?? {};
+const phases = Array.isArray(draft.phases) ? [...draft.phases] : [];
+const errors = Array.isArray(draft.errors) ? [...draft.errors] : [];
+const recoveries = Array.isArray(draft.recoveries) ? draft.recoveries : [];
+const notes = Array.isArray(draft.notes) ? draft.notes : [];
+const outcome = draft.outcome ?? {};
+const requiredPhases = Array.isArray(draft.requiredPhases) ? draft.requiredPhases : [];
+
+// ---- 1. Timing completeness gate ------------------------------------------
+const phasesByName = new Map();
+for (const p of phases) {
+  phasesByName.set(p.phase, p);
+}
+
+const missingTiming = [];
+
+for (const required of requiredPhases) {
+  const existing = phasesByName.get(required);
+  if (!existing) {
+    // Missing entry entirely.
+    const entry = { phase: required, status: "unknown", seconds: null };
+    phases.push(entry);
+    phasesByName.set(required, entry);
+    errors.push({ code: "MISSING_TIMING", phase: required });
+    missingTiming.push(required);
+  } else if (existing.seconds === null || existing.seconds === undefined) {
+    existing.seconds = null;
+    if (!errors.some((e) => e.code === "MISSING_TIMING" && e.phase === required)) {
+      errors.push({ code: "MISSING_TIMING", phase: required });
+    }
+    missingTiming.push(required);
+  }
+}
+
+// ---- 2. totalSeconds derivation -------------------------------------------
+if (!run.totalSeconds && run.started && run.ended) {
+  const started = Date.parse(run.started);
+  const ended = Date.parse(run.ended);
+  if (!Number.isNaN(started) && !Number.isNaN(ended) && ended >= started) {
+    run.totalSeconds = Math.round((ended - started) / 1000);
+  }
+}
+
+// ---- 3. Compose final shape -----------------------------------------------
+const final = {
+  version: "1.0",
+  run,
+  outcome,
+  phases,
+  ...(recoveries.length > 0 ? { recoveries } : {}),
+  ...(errors.length > 0 ? { errors } : {}),
+  ...(notes.length > 0 ? { notes } : { notes: [] }),
+};
+
+const wixDir = join(projectDir, ".wix");
+mkdirSync(wixDir, { recursive: true });
+const runJsonPath = join(wixDir, "run.json");
+writeFileSync(runJsonPath, JSON.stringify(final, null, 2) + "\n");
+
+// ---- 4. Perf one-liner ----------------------------------------------------
+// Format: "Built in <Nm Ss> — design-system <n>s · images (phase 1 + phase 2) <n>s · build+release <n>s"
+const fmtSeconds = (sec) => (sec === null || sec === undefined ? "–" : `${sec}s`);
+const fmtTotal = (sec) => {
+  if (sec === null || sec === undefined) return "–";
+  const m = Math.floor(sec / 60);
+  const s = sec % 60;
+  return `${m}m ${s}s`;
+};
+const phaseSeconds = (name) => {
+  const p = phasesByName.get(name);
+  return p && p.seconds !== null && p.seconds !== undefined ? p.seconds : null;
+};
+const designSystem = phaseSeconds("design-system");
+const img1 = phaseSeconds("image-phase-1-decorative");
+const img2 = phaseSeconds("image-phase-2-entity");
+const imgTotal = img1 !== null && img2 !== null ? img1 + img2 : null;
+const build = phaseSeconds("build");
+const release = phaseSeconds("release") ?? phaseSeconds("preview");
+const buildPlusRelease = build !== null && release !== null ? build + release : null;
+
+const perfLine = `Built in ${fmtTotal(run.totalSeconds)} — design-system ${fmtSeconds(designSystem)} · images (phase 1 + phase 2) ${fmtSeconds(imgTotal)} · build+release ${fmtSeconds(buildPlusRelease)}`;
+
+console.log(JSON.stringify({
+  status: missingTiming.length > 0 ? "partial" : "ok",
+  path: runJsonPath,
+  totalSeconds: run.totalSeconds ?? null,
+  missingTiming,
+  perfLine,
+}, null, 2));

package/skills/wix-headless/scripts/init-site-json.mjs

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+// Write the initial .wix/site.json shape during Setup. Site.json is the
+// single source of truth that every downstream phase reads from / appends
+// to. This script writes the canonical initial structure deterministically
+// so the orchestrator never has to compose the shape inline (which used
+// to be LLM-emitted JSON, with the obvious drift risks).
+//
+// Usage:
+//   node init-site-json.mjs <project-dir> <brand-name> <brand-description> <verticals-csv>
+//
+// Example:
+//   node init-site-json.mjs /tmp/proj "Acme Coffee" "Warm cream-and-forest editorial" "stores,ecom,cms,gift-cards"
+//
+// Behavior:
+//   - Refuses to overwrite an existing .wix/site.json (exit 2). The orchestrator
+//     should call this exactly once during Setup. To re-init for testing, the
+//     caller can rm the file first.
+//   - Creates .wix/ if it doesn't exist.
+//   - Outputs a JSON summary to stdout.
+
+import { writeFileSync, existsSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+
+const [, , projectDir, brandName, brandDescription, verticalsCsv] = process.argv;
+
+if (!projectDir || !brandName || brandDescription === undefined || !verticalsCsv) {
+  console.error("usage: init-site-json.mjs <project-dir> <brand-name> <brand-description> <verticals-csv>");
+  process.exit(2);
+}
+
+const verticals = verticalsCsv
+  .split(",")
+  .map((v) => v.trim())
+  .filter(Boolean);
+
+if (verticals.length === 0) {
+  console.error("init-site-json: <verticals-csv> resolved to zero verticals — cms is always loaded, so this is a bug");
+  process.exit(2);
+}
+
+const wixDir = join(projectDir, ".wix");
+const sitePath = join(wixDir, "site.json");
+
+if (existsSync(sitePath)) {
+  console.error(`init-site-json: ${sitePath} already exists — refusing to overwrite. Setup should call this exactly once.`);
+  process.exit(2);
+}
+
+mkdirSync(wixDir, { recursive: true });
+
+const site = {
+  brand: {
+    name: brandName,
+    description: brandDescription,
+  },
+  seeded: {},
+  designTokens: {},
+  verticals,
+};
+
+writeFileSync(sitePath, JSON.stringify(site, null, 2) + "\n");
+
+console.log(JSON.stringify({ status: "ok", path: sitePath, verticals }, null, 2));