@wix/agent-skills 1.35.1 → 1.36.1

package/skills/wix-replatform/resources/rp-target-wix/lib/blog-author-attribution.js

@@ -1,165 +0,0 @@
-'use strict';
-
-// Blog post author attribution: resolve a real Wix member for each distinct source blog author,
-// instead of attributing every imported post to the site owner.
-//
-// THE PITFALL: every imported blog post could carry the SAME memberId -- the site owner's own
-// auto-created user-member -- regardless of which WordPress author actually wrote the post. The
-// source data (data/source-extract/post.ndjson, via `_embedded.author`) names each post's
-// distinct author, and all of them were discarded on import in favor of one hardcoded
-// `WIX_BLOG_AUTHOR_MEMBER_ID`. Root cause: a stale
-// assumption in wix-writers.js's members section ("attribute-to-owner blog imports need no
-// member provisioning") -- a deliberate but wrong simplification, because Wix Blog's `memberId`
-// is required and has no "unauthored" option.
-//
-// The sanctioned fix, verified directly against Wix's own documentation -- the internal skill
-// doc "How to Create Blog Posts" (dev.wix.com/docs/api-reference/business-solutions/blog/skills/
-// how-to-create-blog-posts, "Part 0: Get an Author/Member ID") -- is to CREATE a member when
-// there is no existing member to reuse for an author: its `profile.nickname` (derived from
-// `contact.firstName`) is the name the blog displays as the author, and "If the user named an
-// author, use their name." The same doc, and wix-writers.js's own VERIFIED notes near
-// `createMember`, confirm Create Member sends no email and fires no signup-automation trigger --
-// member creation here is silent, not a notification risk.
-//
-// This creates ONE member per distinct SOURCE AUTHOR, never one per post: callers must resolve
-// through a crosswalk keyed by `sourceAuthorId` (see the `crosswalk` param below) so two posts by
-// the same WordPress author resolve to the same Wix member, and a resumed/re-run import never
-// creates a second member for an author it already provisioned. Recording that crosswalk row
-// after a successful create is the CALLER's responsibility (mirrors `customer-member.js` /
-// `member-crosswalk.js`'s own ensure-then-persist split for the order-buyer member pass) --
-// this module only resolves and creates; see rp-import-codegen/SKILL.md's "Blog post author
-// attribution" section for the generated call site that does both.
-//
-// Not every migration source populates author info on every post (`_embedded.author` is a
-// WordPress `_embed` convenience, not a guarantee across every source platform this toolkit
-// supports) -- resolution falls back to the existing site-owner attribution when a post simply
-// has no source author data, rather than making author resolution a hard requirement that blocks
-// import.
-
-const w = require('./wix-writers.js');
-
-const OUTCOMES = Object.freeze([
-  'blog-author-reconciled-existing', // crosswalk already had a member for this source author
-  'blog-author-created', // no crosswalk row for this source author; a new member was created
-  'blog-author-owner-fallback', // post carries no source author info at all; owner attribution
-]);
-
-// RFC 2606 reserves `.invalid` for addresses guaranteed never to resolve or be deliverable --
-// unlike `example.com`/`example.org`, which some mail systems do attempt to resolve, `.invalid`
-// is the correct TLD for a placeholder address that must never receive mail. The local part
-// carries ONLY the opaque source author id (never the author's real name or any other PII) --
-// the whole point of this fix is that the human's NAME is what is supposed to show up as
-// "posted by X" on the blog, deliberately, via `profile.nickname`/`contact.firstName`; the
-// placeholder address that makes the member creatable carries none of it. The domain is scoped
-// per `siteId` so the SAME source author id across two different projects' migrations can never
-// collide into the same placeholder address -- loginEmail uniqueness is per-site in Wix Members,
-// so this costs nothing and removes any cross-project ambiguity from the scheme.
-//
-// Pattern: `blog-author-{hash(sourceAuthorId)}@{hash(siteId)}.invalid` (see the collision fix
-// below for why each component is a hash of the raw value rather than the raw value itself).
-//
-// COLLISION FIX: an earlier version of this function
-// derived the token via a lossy, human-readable sanitization (lowercase, then collapse every run
-// of non-alphanumeric characters to a single `-`). That is not injective: two different raw
-// values that differ only in WHICH separator character they use collapse to the identical token
-// -- e.g. sourceAuthorId `'1-2'` and `'1@2'` both sanitized to `'1-2'`, so two genuinely distinct
-// WordPress authors would have collided onto the SAME placeholder `loginEmail` and therefore the
-// SAME Wix member, silently misattributing one author's posts to the other. The fix derives the
-// token from a hash of the RAW, un-sanitized value instead: distinct inputs can never collide
-// (short of a SHA-1 collision). This token is never exposed as user-facing content -- it only
-// ever appears inside the `.invalid` placeholder email's local part; the real, human-readable
-// author name goes solely into `profile.nickname`/`contact.firstName` (see
-// `resolveBlogAuthorMemberId` below) -- so there is no readability requirement to trade off here.
-function sanitizeForEmailToken(value) {
-  const raw = value === undefined || value === null ? '' : String(value);
-  return require('node:crypto').createHash('sha1').update(raw).digest('hex').slice(0, 16);
-}
-
-function buildPlaceholderAuthorEmail({ sourceAuthorId, siteId }) {
-  if (sourceAuthorId === undefined || sourceAuthorId === null || sourceAuthorId === '') {
-    throw new Error('buildPlaceholderAuthorEmail requires sourceAuthorId');
-  }
-  const authorToken = sanitizeForEmailToken(sourceAuthorId);
-  const siteToken = sanitizeForEmailToken(siteId || 'site');
-  return `blog-author-${authorToken}@${siteToken}.invalid`;
-}
-
-// CORRECTED: this module previously paced its own Create
-// Member write against a module-private `lastAuthorMemberWriteAt` clock, entirely disjoint from
-// `ensureMember`'s own `lastMemberWriteAt` in wix-writers.js -- the two never saw each other's
-// writes despite sharing the same `MEMBER_WRITE_MIN_INTERVAL_MS` constant. wix-writers.js's own
-// comment documents the >=1s Create Member floor as a constraint on the Wix API endpoint
-// itself, not on whichever function happens to call it, and rp-import-codegen/SKILL.md's
-// generated importers run passes sequentially in ONE process -- so a migration's member
-// pass (`ensureMember`) and blog-author pass (`resolveBlogAuthorMemberId`) could issue two
-// Create Member calls under 1s apart. Fixed by going through wix-writers.js's exported
-// `pacedCreateMember`, which reads and stamps the SAME clock `ensureMember` uses, so every
-// Create Member call in the process -- regardless of which pass issues it -- is correctly
-// spaced against every other one.
-if (typeof w.pacedCreateMember !== 'function') {
-  throw new Error('blog-author-attribution.js requires wix-writers.js to export pacedCreateMember');
-}
-
-// wix: the Wix API client (wix-writers.js's createWixClient()).
-// sourceAuthorId / sourceAuthorName: pulled straight from the source post's author reference
-//   (e.g. WordPress `_embedded.author[0].id`/`.name`) -- null/undefined/'' means the source gave
-//   no author for this post at all.
-// crosswalk: an object exposing async get(sourceAuthorId) -> { memberId, loginEmail } | null,
-//   such as `member-crosswalk.js`'s createProjectMemberCrosswalk({ projectDir, sourceSystem,
-//   sourceEntityType: 'blog-author' }). Required whenever sourceAuthorId is present -- this is
-//   what makes repeat resolution of the same author idempotent across resumed runs.
-// siteId: folded into the placeholder email's domain (see buildPlaceholderAuthorEmail).
-// ownerMemberId: the existing single-owner attribution fallback, used only when the source gives
-//   no author info for this post.
-async function resolveBlogAuthorMemberId(wix, {
-  sourceAuthorId = null,
-  sourceAuthorName = null,
-  crosswalk = null,
-  siteId = null,
-  ownerMemberId = null,
-  safeModeOptions,
-  sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
-} = {}) {
-  if (sourceAuthorId === null || sourceAuthorId === undefined || sourceAuthorId === '') {
-    if (!ownerMemberId) {
-      throw new Error('resolveBlogAuthorMemberId: post has no source author and no ownerMemberId fallback was supplied');
-    }
-    return { outcome: 'blog-author-owner-fallback', memberId: String(ownerMemberId), created: false };
-  }
-  if (!crosswalk || typeof crosswalk.get !== 'function') {
-    throw new Error('resolveBlogAuthorMemberId: a post with a source author requires a crosswalk with an async get(sourceAuthorId) lookup');
-  }
-
-  const existing = await crosswalk.get(sourceAuthorId);
-  if (existing && existing.memberId) {
-    return { outcome: 'blog-author-reconciled-existing', memberId: String(existing.memberId), created: false };
-  }
-
-  const displayName = (sourceAuthorName && String(sourceAuthorName).trim()) || `Author ${sourceAuthorId}`;
-  const loginEmail = buildPlaceholderAuthorEmail({ sourceAuthorId, siteId });
-
-  const member = await w.pacedCreateMember(wix, { email: loginEmail, name: displayName }, safeModeOptions, sleep);
-  // createMember only ever skips on an empty email (buildCreateMemberRequest's own guard);
-  // buildPlaceholderAuthorEmail never produces one, so reaching `skipped` means a caller bypassed
-  // it -- surfaced as an error rather than silently falling through to the owner.
-  if (member && member.skipped) {
-    throw new Error(`resolveBlogAuthorMemberId: member creation was skipped unexpectedly: ${member.reason}`);
-  }
-  if (!member || !member.id) {
-    throw new Error('resolveBlogAuthorMemberId: Create Member returned no id');
-  }
-  return {
-    outcome: 'blog-author-created',
-    memberId: String(member.id),
-    created: true,
-    loginEmail,
-    displayName,
-  };
-}
-
-module.exports = {
-  OUTCOMES,
-  sanitizeForEmailToken,
-  buildPlaceholderAuthorEmail,
-  resolveBlogAuthorMemberId,
-};

package/skills/wix-replatform/resources/rp-target-wix/lib/blog-post-build-client.js

@@ -1,60 +0,0 @@
-'use strict';
-
-const WIXAPIS = 'https://www.wixapis.com';
-const writers = require('./wix-writers');
-
-function unwrap(response, field) {
-  const value = response?.[field];
-  if (!value) throw new Error(`Wix Blog response lacks ${field}`);
-  return value;
-}
-function readUrl(surface, id) {
-  const encoded = encodeURIComponent(id);
-  return `${WIXAPIS}/blog/v3/${surface}/${encoded}?fieldsets=RICH_CONTENT&fieldsets=URL`;
-}
-function createBlogBuildClient(wix, { fetchPage, fetchImage } = {}) {
-  if (!wix || typeof wix.send !== 'function') throw new Error('blog build client needs wix.send');
-  return {
-    async createDraft(post) {
-      const response = await wix.send({ method: 'POST', url: `${WIXAPIS}/blog/v3/draft-posts`,
-        body: { draftPost: post, fieldsets: ['RICH_CONTENT', 'URL'] } });
-      return unwrap(response, 'draftPost');
-    },
-    async updateDraft(id, projection) {
-      const response = await wix.send({ method: 'PATCH', url: `${WIXAPIS}/blog/v3/draft-posts/${encodeURIComponent(id)}`,
-        body: { action: 'UPDATE', draftPost: { id, ...projection }, fieldsets: ['RICH_CONTENT', 'URL'] } });
-      return unwrap(response, 'draftPost');
-    },
-    async publishDraft(id) { return writers.publishDraftPost(wix, id); },
-    async getDraft(id) { return unwrap(await wix.send({ method: 'GET', url: readUrl('draft-posts', id) }), 'draftPost'); },
-    async getPost(id) { return unwrap(await wix.send({ method: 'GET', url: readUrl('posts', id) }), 'post'); },
-    async listDrafts({ cursor } = {}) {
-      const params = new URLSearchParams({ 'paging.limit': '100', status: 'UNPUBLISHED' });
-      if (cursor?.startsWith('offset:')) params.set('paging.offset', cursor.slice('offset:'.length));
-      else if (cursor) params.set('paging.cursor', cursor);
-      const response = await wix.send({ method: 'GET', url: `${WIXAPIS}/blog/v3/draft-posts?${params}` });
-      const drafts = response?.draftPosts;
-      if (!Array.isArray(drafts)) throw new Error('Wix Blog list response lacks draftPosts');
-      // Blog List Draft Posts exposes metaData; other Wix list APIs use pagingMetadata.
-      // Accept either documented envelope, but never silently truncate an uncertain page.
-      const metadata = response?.metaData || response?.pagingMetadata;
-      if (!metadata) throw new Error('Wix Blog list response lacks pagination metadata');
-      let nextCursor = metadata.cursors?.next || metadata.nextCursor || null;
-      if (!nextCursor && Number.isFinite(metadata.total) && Number.isFinite(metadata.offset) &&
-        metadata.offset + drafts.length < metadata.total) {
-        if (!drafts.length) throw new Error('Wix Blog list made no offset progress');
-        nextCursor = `offset:${metadata.offset + drafts.length}`;
-      }
-      if (!nextCursor && drafts.length === 100 && !Number.isFinite(metadata.total)) {
-        throw new Error('Wix Blog list ended on a full page without pagination evidence');
-      }
-      return { drafts, nextCursor };
-    },
-    async deletePost(id) { return writers.deletePost(wix, id); },
-    async deleteDraft(id) { return wix.send(writers.buildDeleteDraftPostRequest(id)); },
-    ...(fetchPage ? { fetchPage } : {}),
-    ...(fetchImage ? { fetchImage } : {}),
-  };
-}
-
-module.exports = { createBlogBuildClient };

package/skills/wix-replatform/resources/rp-target-wix/lib/blog-post-build-duplicates.js

@@ -1,201 +0,0 @@
-'use strict';
-
-const ledger = require('./blog-post-build-ledger');
-const reports = require('./blog-post-build-report');
-
-function pairKey(key, extraId) { return `${key}\u0000${extraId}`; }
-function currentPair(projectDir, key, extraId) {
-  return ledger.fold(ledger.readRows(projectDir)).duplicates.get(pairKey(key, extraId));
-}
-function append(projectDir, key, recordedDraftId, extraDraftId, event, rest = {}) {
-  return ledger.appendRow(projectDir, { kind: 'duplicate', sourceStableKey: key,
-    recordedDraftId, extraDraftId, event, ...rest });
-}
-function isNotFound(error) {
-  if (error?.status !== 404) return false;
-  const code = error.code || error.applicationErrorCode || error.details?.code ||
-    error.body?.details?.applicationError?.code;
-  const message = error.body?.message || error.message || '';
-  return ['NOT_FOUND', 'ENTITY_NOT_FOUND'].includes(code) ||
-    (!code && error.outcomeKnown === true && /^entity not found\b/i.test(String(message)));
-}
-async function readOrNull(fn, id) {
-  try { return await fn(id); } catch (error) { if (isNotFound(error)) return null; throw error; }
-}
-async function listAll(client) {
-  const drafts = [];
-  let cursor = null;
-  const cursors = new Set();
-  for (let n = 0; n < 1000; n += 1) {
-    const page = await client.listDrafts({ cursor });
-    if (!Array.isArray(page?.drafts)) throw new Error('draft listing lacks drafts array');
-    drafts.push(...page.drafts);
-    if (!page.nextCursor) return drafts;
-    if (cursors.has(page.nextCursor)) throw new Error('draft listing cursor repeated');
-    cursors.add(page.nextCursor);
-    cursor = page.nextCursor;
-  }
-  throw new Error('draft listing page cap reached');
-}
-function sourceRows(state, key) {
-  return state.posts.get(key)?.rows || [];
-}
-function intentAndCreate(state, key) {
-  const rows = sourceRows(state, key);
-  const create = [...rows].reverse().find(row => row.kind === 'phase' && ['drafted', 'contain-drafted'].includes(row.phase));
-  return {
-    intent: [...rows].reverse().find(row => row.seq < create?.seq && row.kind === 'phase' &&
-      ['creating', 'contain-recreating'].includes(row.phase)),
-    create,
-  };
-}
-function recordedElsewhere(state, id, key, crosswalk) {
-  if (typeof crosswalk?.idOwners !== 'function') return true;
-  for (const [otherKey, post] of state.posts) {
-    if (otherKey !== key && post.rows.some(row => row.draftId === id || row.postId === id)) return true;
-  }
-  return Boolean(crosswalk?.idOwners?.(id)?.some(owner => String(owner) !== key));
-}
-function assessProvenance(state, key, extraId, draft, crosswalk) {
-  const { intent, create } = intentAndCreate(state, key);
-  const sourceFp = intent?.fingerprint;
-  const creation = Date.parse(draft?.createdDate || draft?.createdAt);
-  const edited = Date.parse(draft?.editedDate || draft?.updatedDate);
-  const started = Date.parse(intent?.ts);
-  const finished = Date.parse(create?.ts);
-  const tests = {
-    fingerprint: Boolean(draft && sourceFp && ledger.fingerprint(draft) === sourceFp),
-    storedBody: Boolean(draft && create?.storedBodySha && ledger.bodySha(draft) === create.storedBodySha),
-    creationWindow: Number.isFinite(creation) && Number.isFinite(started) && Number.isFinite(finished) &&
-      creation >= started - 5 * 60_000 && creation <= finished,
-    unedited: Number.isFinite(edited) && Number.isFinite(creation) && Math.abs(edited - creation) <= 1000,
-    unowned: !recordedElsewhere(state, extraId, key, crosswalk),
-  };
-  return { status: Object.values(tests).every(Boolean) ? 'consistent' : 'inconsistent', tests,
-    title: draft?.title || null, createdDate: draft?.createdDate || draft?.createdAt || null };
-}
-async function recordProvenance(projectDir, key, extraId, client, crosswalk, alreadyRead) {
-  const pair = currentPair(projectDir, key, extraId);
-  if (!pair || pair.closed) throw new Error('no open duplicate pair');
-  let draft = alreadyRead;
-  let readError;
-  if (!draft) {
-    try { draft = await client.getDraft(extraId); }
-    catch (error) { readError = error.message; }
-  }
-  const state = ledger.fold(ledger.readRows(projectDir));
-  const evidence = draft ? assessProvenance(state, key, extraId, draft, crosswalk)
-    : { status: 'inconsistent', tests: {}, readError };
-  append(projectDir, key, pair.recordedDraftId, extraId, 'provenance', { evidence });
-  return evidence;
-}
-async function finishPendingEvidence(projectDir, client, crosswalk) {
-  const state = ledger.fold(ledger.readRows(projectDir));
-  for (const pair of state.duplicates.values()) {
-    if (!pair.closed && !pair.evidence) await recordProvenance(projectDir, pair.sourceStableKey, pair.extraDraftId, client, crosswalk);
-  }
-}
-async function detectExtraDrafts(projectDir, client, crosswalk, onlyKey) {
-  const state = ledger.fold(ledger.readRows(projectDir));
-  const targets = [...state.posts.entries()].filter(([key, post]) => (!onlyKey || key === onlyKey) &&
-    post.rows.some(row => ['drafted', 'contain-drafted'].includes(row.phase) && row.recreatedAfterIntent));
-  if (!targets.length) return [];
-  const drafts = await listAll(client);
-  const added = [];
-  for (const [key, post] of targets) {
-    const { intent, create } = intentAndCreate(state, key);
-    if (!intent || !create) continue;
-    const intentBody = [...post.rows].reverse().find(row => row.kind === 'desired-state' &&
-      row.seq < intent.seq);
-    if (!intentBody) throw new Error(`blog duplicate ${key}: create intent has no pinned body`);
-    const expectedTitle = ledger.loadGeneration(projectDir, intentBody.snapshotSha, key).desiredPost.title;
-    for (const draft of drafts) {
-      if (draft.id === create.draftId || draft.title !== expectedTitle) continue;
-      if (currentPair(projectDir, key, draft.id)) continue;
-      // List responses need not include every fingerprint field; use one full read
-      // for matching and provenance rather than missing a late-visible duplicate.
-      let full;
-      try { full = await client.getDraft(draft.id); }
-      catch (error) {
-        append(projectDir, key, create.draftId, draft.id, 'detected');
-        append(projectDir, key, create.draftId, draft.id, 'provenance',
-          { evidence: { status: 'inconsistent', tests: {}, readError: error.message } });
-        added.push({ sourceStableKey: key, extraDraftId: draft.id });
-        continue;
-      }
-      if (ledger.fingerprint(full) !== intent.fingerprint) continue;
-      append(projectDir, key, create.draftId, draft.id, 'detected');
-      added.push({ sourceStableKey: key, extraDraftId: draft.id });
-      await recordProvenance(projectDir, key, draft.id, client, crosswalk, full);
-    }
-  }
-  return added;
-}
-function ensureEvidence(pair, expected = 'consistent') {
-  if (!pair || pair.closed || pair.evidence?.status !== expected) throw new Error(`duplicate needs current ${expected} evidence`);
-}
-function confirmOwnership(projectDir, key, extraId, chosenBy, note) {
-  return ledger.withLock(projectDir, async () => {
-    const pair = currentPair(projectDir, key, extraId);
-    ensureEvidence(pair);
-    if (!String(chosenBy || '').trim() || !String(note || '').trim()) throw new Error('ownership needs named person and their explanation');
-    const row = append(projectDir, key, pair.recordedDraftId, extraId, 'ownership-confirmed', { chosenBy, note });
-    return { row, ...(await reports.refreshBlogHandoff(projectDir)) };
-  });
-}
-function keepOrNotImporter(projectDir, key, extraId, event, chosenBy, note) {
-  return ledger.withLock(projectDir, async () => {
-    const pair = currentPair(projectDir, key, extraId);
-    if (!pair || pair.closed) throw new Error('no open duplicate pair');
-    if (!['kept', 'not-importer'].includes(event)) throw new Error('invalid duplicate closure');
-    if (!String(note || '').trim()) throw new Error('the person’s note is required');
-    if (event === 'kept' && !String(chosenBy || '').trim()) throw new Error('chosenBy required');
-    const row = append(projectDir, key, pair.recordedDraftId, extraId, event, { chosenBy, note });
-    return { row, ...(await reports.refreshBlogHandoff(projectDir)) };
-  });
-}
-async function deleteConfirmedExtra(projectDir, key, extraId, chosenBy, note, client, crosswalk) {
-  return ledger.withLock(projectDir, async () => {
-    let pair = currentPair(projectDir, key, extraId);
-    ensureEvidence(pair);
-    if (!pair.confirmation || !String(chosenBy || '').trim() || !String(note || '').trim()) {
-      throw new Error('current ownership confirmation and a separate named delete choice required');
-    }
-    if (!pair.choice) append(projectDir, key, pair.recordedDraftId, extraId, 'delete-chosen', { chosenBy, note });
-    const draft = await readOrNull(value => client.getDraft(value), extraId);
-    if (!draft) {
-      const post = await readOrNull(value => client.getPost(value), extraId);
-      if (!post) {
-        append(projectDir, key, pair.recordedDraftId, extraId, 'removed');
-        return (await reports.refreshBlogHandoff(projectDir)).report;
-      }
-      append(projectDir, key, pair.recordedDraftId, extraId, 'unresolved',
-        { evidence: { status: 'inconsistent', tests: { unpublished: false } } });
-      return (await reports.refreshBlogHandoff(projectDir)).report;
-    }
-    const evidence = assessProvenance(ledger.fold(ledger.readRows(projectDir)), key, extraId, draft, crosswalk);
-    if (evidence.status !== 'consistent') {
-      append(projectDir, key, pair.recordedDraftId, extraId, 'unresolved', { evidence });
-      return (await reports.refreshBlogHandoff(projectDir)).report;
-    }
-    if (typeof client.deleteDraft !== 'function') throw new Error('client needs deleteDraft for chosen duplicate deletion');
-    await client.deleteDraft(extraId);
-    const draftAfter = await readOrNull(value => client.getDraft(value), extraId);
-    const postAfter = await readOrNull(value => client.getPost(value), extraId);
-    if (draftAfter || postAfter) throw new Error('extra draft deletion not confirmed on both surfaces');
-    pair = currentPair(projectDir, key, extraId);
-    append(projectDir, key, pair.recordedDraftId, extraId, 'removed');
-    return (await reports.refreshBlogHandoff(projectDir)).report;
-  });
-}
-
-function recheckProvenance(projectDir, key, extraId, client, crosswalk) {
-  return ledger.withLock(projectDir, async () => {
-    const evidence = await recordProvenance(projectDir, key, extraId, client, crosswalk);
-    return { evidence, ...(await reports.refreshBlogHandoff(projectDir)) };
-  });
-}
-
-module.exports = { pairKey, currentPair, assessProvenance,
-  finishPendingEvidence, detectExtraDrafts, confirmOwnership, keepOrNotImporter,
-  deleteConfirmedExtra, recheckProvenance };