@wix/agent-skills 1.33.1 → 1.35.0

package/skills/wix-replatform/lib/destination-handoff.js

@@ -0,0 +1,62 @@
+'use strict';
+
+// Work that remains on an Editor destination after the backend import, folded
+// into `execution/completion-report.json.operatorActions` (projected to the post-execution
+// handoff). Pre-import recovery lives in orchestration/user-actions/ and is not repeated here.
+// The notification item is produced by setup and reused, never duplicated.
+const fs = require('node:fs/promises');
+const path = require('node:path');
+const { readReceipt } = require('./destination.js');
+
+const EDITOR_LABEL = { studio: 'Wix Studio', harmony: 'Wix Harmony' };
+
+async function readJsonIfExists(filePath) {
+  try { return JSON.parse(await fs.readFile(filePath, 'utf8')); } catch { return null; }
+}
+
+// A released website (frontend completion receipt with a released state) resolves both items.
+function websiteReleased(frontendCompletion) {
+  return Boolean(frontendCompletion
+    && ['complete', 'complete_with_warnings'].includes(frontendCompletion.status)
+    && frontendCompletion.release && frontendCompletion.release.status === 'released');
+}
+
+function destinationOperatorActions(receipt, { frontendCompletion = null } = {}) {
+  if (!receipt || !EDITOR_LABEL[receipt.requestedSiteType] || !receipt.metaSiteId || receipt.status !== 'verified') return [];
+  if (websiteReleased(frontendCompletion)) return [];
+  const editor = EDITOR_LABEL[receipt.requestedSiteType];
+  const editorLink = receipt.editorUrl ? ` Editor: ${receipt.editorUrl}.` : '';
+  const generated = receipt.creationMethod === 'harmony_generation'
+    ? ' The site was created by Harmony generation: its generated pages, AI-generated text and images are placeholders until reviewed or replaced, even when the site looks finished; their existence never resolves this item.'
+    : '';
+  const publication = receipt.publication && receipt.publication.state === 'unpublished'
+    ? `verified unpublished at ${receipt.publication.checkedAt}`
+    : 'publication state not verified as unpublished — an unresolved check, not "unpublished"';
+  return [
+    {
+      code: 'editor_website_unfinished',
+      severity: 'high',
+      action: `Site owner/designer: the ${editor} website for site ${receipt.metaSiteId} is not built — customers cannot use the migrated website yet.${editorLink} Open the verified editor, complete the pages and required app surfaces for the imported data, then review/publish through the authorized cutover workflow. Resolve with bound website review/release evidence; backend import counts alone do not resolve this.${generated}`,
+      deadlineReason: 'before switching traffic',
+      entity: 'website',
+      affectedCount: 1,
+    },
+    {
+      code: 'editor_publication_outstanding',
+      severity: 'high',
+      action: `Cutover Operator/authorized publisher: site ${receipt.metaSiteId} has no public website until it is released (${publication}). Complete the website and public-site checks, then authorize and publish through the supported workflow. RePlatform never publishes it. Resolve with publication and public-site evidence.`,
+      deadlineReason: 'before switching traffic',
+      entity: 'website',
+      affectedCount: 1,
+    },
+  ];
+}
+
+async function projectDestinationOperatorActions(projectDir) {
+  const receipt = await readReceipt(projectDir);
+  if (!receipt || receipt.invalid) return [];
+  const frontendCompletion = await readJsonIfExists(path.join(projectDir, 'website', 'completion.json'));
+  return destinationOperatorActions(receipt, { frontendCompletion });
+}
+
+module.exports = { destinationOperatorActions, projectDestinationOperatorActions, websiteReleased };

package/skills/wix-replatform/lib/destination-http.js

@@ -0,0 +1,81 @@
+'use strict';
+
+// Per-call time limits: every destination HTTP call is bounded by an explicit
+// client-side timeout, and every wait goes through an injectable clock so the bounds can be
+// proven with a fake clock instead of real minutes.
+
+class CallTimeoutError extends Error {
+  constructor(timeoutMs) {
+    super(`request timed out after ${timeoutMs} ms`);
+    this.code = 'call_timeout';
+    this.timeoutMs = timeoutMs;
+  }
+}
+
+function realClock() {
+  return {
+    now: () => Date.now(),
+    // A cancelled timer never resolves; nothing waits on it after cancellation.
+    timer(ms) {
+      let handle = null;
+      const promise = new Promise((resolve) => {
+        handle = setTimeout(resolve, Math.max(0, ms));
+      });
+      return { promise, cancel() { clearTimeout(handle); } };
+    },
+    sleep(ms) { return this.timer(ms).promise; },
+  };
+}
+
+// One HTTP call: fetch plus body read, aborted at `timeoutMs`. Resolves to
+// `{ status, headers, text, json }` (json is null when the body is not JSON) or rejects with
+// CallTimeoutError (timeout) / the transport error (network). Never logs headers or bodies.
+async function boundedRequest({ fetch, clock }, url, init, timeoutMs) {
+  if (!(timeoutMs > 0)) throw new CallTimeoutError(0);
+  const controller = new AbortController();
+  const timer = clock.timer(timeoutMs);
+  let timedOut = false;
+  const timeout = timer.promise.then(() => {
+    timedOut = true;
+    controller.abort();
+    throw new CallTimeoutError(timeoutMs);
+  });
+  const call = (async () => {
+    const response = await fetch(url, { ...init, signal: controller.signal });
+    const text = await response.text();
+    let json = null;
+    try { json = text ? JSON.parse(text) : null; } catch { json = null; }
+    return {
+      status: response.status,
+      retryAfter: response.headers && typeof response.headers.get === 'function' ? response.headers.get('retry-after') : null,
+      text,
+      json,
+    };
+  })();
+  try {
+    return await Promise.race([call, timeout]);
+  } catch (error) {
+    if (timedOut) throw new CallTimeoutError(timeoutMs);
+    throw error;
+  } finally {
+    if (!timedOut) timer.cancel();
+    call.catch(() => {});
+    timeout.catch(() => {});
+  }
+}
+
+// Retry-After in seconds or an HTTP date; returns milliseconds or null.
+function retryAfterMs(value, nowMs) {
+  if (value === null || value === undefined || value === '') return null;
+  const text = String(value).trim();
+  if (/^\d+$/.test(text)) return Number(text) * 1000;
+  const date = Date.parse(text);
+  if (Number.isNaN(date)) return null;
+  return Math.max(0, date - nowMs);
+}
+
+function isTransientStatus(status) {
+  return status === 429 || (status >= 500 && status <= 599);
+}
+
+module.exports = { CallTimeoutError, boundedRequest, isTransientStatus, realClock, retryAfterMs };

package/skills/wix-replatform/lib/destination-route.js

@@ -0,0 +1,98 @@
+'use strict';
+
+// The router's destination gate. It reads the creation receipt before the
+// WIX_SITE_ID check (an Editor site's ID is written to config/wix.env before verification
+// finishes), and it requires an explicit site type before a fresh new-site creation.
+// Returns a route, or null to continue with the router's existing destination checks.
+const fs = require('node:fs/promises');
+const path = require('node:path');
+const { isEditorSiteType, isNewSiteStrategy, readSiteTypeDecision } = require('./orchestration-decisions.js');
+const { readReceipt, validateReceipt } = require('./destination.js');
+
+const RESOURCE = 'resources/rp-destination/';
+
+async function recoveryAnswered(projectDir, receipt) {
+  const requestId = receipt.recovery && receipt.recovery.requestId;
+  if (!requestId || !/^uar_[0-9a-f-]+$/.test(requestId)) return false;
+  try {
+    const request = JSON.parse(await fs.readFile(path.join(projectDir, 'orchestration', 'user-actions', `${requestId}.json`), 'utf8'));
+    return request.status === 'answered';
+  } catch {
+    return false;
+  }
+}
+
+async function destinationGate(projectDir, decisions, { targetSiteStrategy, siteIdValue, scaffoldStatus }) {
+  const choice = readSiteTypeDecision(decisions);
+  const receipt = await readReceipt(projectDir);
+  if (receipt) {
+    const errors = validateReceipt(receipt);
+    if (errors.length) return { ok: false, nextState: 'failed', nextResource: RESOURCE, reason: 'destination_receipt_invalid', errors };
+    if (choice && !choice.errors.length && choice.siteType !== receipt.requestedSiteType) {
+      return { ok: true, nextState: 'blocked', nextResource: RESOURCE, reason: 'destination_type_conflict', blocking: true, errors: [{ receipt: receipt.requestedSiteType, decision: choice.siteType }] };
+    }
+    // Headless keeps the wrapper's WIX_SCAFFOLD_STATUS contract unchanged.
+    if (!isEditorSiteType(receipt.requestedSiteType)) return null;
+    switch (receipt.status) {
+      case 'verified':
+        if (!siteIdValue) return { ok: true, nextState: 'destination_running', nextResource: RESOURCE, reason: 'destination_binding_pending' };
+        if (siteIdValue !== receipt.metaSiteId) return { ok: true, nextState: 'blocked', nextResource: RESOURCE, reason: 'destination_binding_conflict', blocking: true };
+        return null;
+      case 'in_progress':
+      case 'created':
+        // The coordinator resumes without a second create (an interrupted attempt becomes ambiguous).
+        return { ok: true, nextState: 'destination_running', nextResource: RESOURCE, reason: 'destination_creation_resumable' };
+      default:
+        if (await recoveryAnswered(projectDir, receipt)) {
+          return { ok: true, nextState: 'destination_running', nextResource: RESOURCE, reason: 'destination_recovery_answered' };
+        }
+        return {
+          ok: true,
+          nextState: 'blocked',
+          nextResource: RESOURCE,
+          reason: `destination_${receipt.status}`,
+          blocking: true,
+          errors: receipt.error ? [{ code: receipt.error.code, requestId: receipt.recovery ? receipt.recovery.requestId : null }] : [],
+        };
+    }
+  }
+  // Legacy/confirmed destinations and prior Headless wrapper attempts keep the existing checks:
+  // a missing historical choice is never reinterpreted as a new-site request.
+  if (siteIdValue || scaffoldStatus !== undefined) return null;
+  if (!isNewSiteStrategy(targetSiteStrategy)) return null;
+  if (!choice) {
+    return { ok: true, nextState: 'awaiting_destination_strategy', nextResource: RESOURCE, reason: 'missing_target_site_type' };
+  }
+  if (choice.errors.length) {
+    return { ok: false, nextState: 'failed', nextResource: 'resources/rp-project-intake/', reason: 'invalid_target_site_type', errors: choice.errors };
+  }
+  return null;
+}
+
+// A later resume repeats the readback before setup. The router has no network access,
+// so it requires the receipt's last `unpublished` readback to be recent whenever the next step
+// would write to a receipt-backed Editor site (setup or import). Otherwise it routes to
+// rp-destination, whose coordinator runs one fresh readback (never a create) and either
+// re-verifies or blocks with the publication recovery request.
+const PUBLICATION_FRESH_MS = 10 * 60_000;
+const DOWNSTREAM_STATES = new Set(['executing_setup', 'executing_import']);
+
+async function publicationRecheckGate(projectDir, route, { now = Date.now() } = {}) {
+  if (!route || !DOWNSTREAM_STATES.has(route.nextState)) return route;
+  let receipt;
+  try { receipt = await readReceipt(projectDir); } catch { receipt = null; }
+  if (!receipt || receipt.invalid || !isEditorSiteType(receipt.requestedSiteType) || receipt.status !== 'verified') return route;
+  const publication = receipt.publication || {};
+  const checkedAt = Date.parse(publication.checkedAt);
+  const age = now - checkedAt;
+  if (publication.state === 'unpublished' && Number.isFinite(checkedAt) && age >= 0 && age <= PUBLICATION_FRESH_MS) return route;
+  return {
+    ok: true,
+    nextState: 'destination_running',
+    nextResource: RESOURCE,
+    reason: 'destination_publication_recheck',
+    deferredState: route.nextState,
+  };
+}
+
+module.exports = { PUBLICATION_FRESH_MS, destinationGate, publicationRecheckGate };