@wix/agent-skills 1.33.0 → 1.34.0

package/skills/wix-replatform/scripts/url-redirects.js

@@ -0,0 +1,286 @@
+#!/usr/bin/env node
+'use strict';
+
+// Old-link preservation helpers: plan, apply and verify redirects after the destination
+// website exists. Deterministic; prints counts and exceptions only (never response bodies).
+// Backend import stays plan-only and never calls apply/verify; the cutover flow decides when
+// to run them. None of these modes publishes pages, changes DNS or sends notifications.
+//
+//   sources --project <dir> --input <file.json>   normalize source redirect maps + coverage
+//   import-targets --project <dir>                 plan captured imported destinations
+//   report  --project <dir>                       rebuild plan + operator report, no network
+//   plan    --project <dir> [--wix-env <file>]    plan; with --wix-env also reads site inventory
+//   apply   --project <dir> --wix-env <file> [--exclusive-edit-window-confirmed]
+//   verify  --project <dir> --stage preparation --connect-host <host> [--connect-port <n>]
+//   verify  --project <dir> --stage verified_public --after-dns-switch
+//   retire-import-plan --project <dir> --wix-env <file> --source-key <key>
+//     --from <path> --to <path> --evidence <reference>  (local retirement; no remote delete)
+//
+// Optional: --concurrency <n> --timeout-ms <n> --retries <n>
+//
+// Credentials (from --wix-env): WIX_SITE_ID plus WIX_API_KEY or WIX_AUTH_TOKEN for reads.
+// Writes need Manage SEO Settings and an explicit identity declaration:
+// APP: WIX_REDIRECTS_APP_TOKEN, WIX_REDIRECTS_APP_SITE_ID, WIX_REDIRECTS_CREDENTIAL_IDENTITY=APP.
+// Wix user: WIX_AUTH_TOKEN, WIX_SITE_ID, WIX_REDIRECTS_CREDENTIAL_IDENTITY=WIX_USER.
+// A site-member token is not a Wix user credential; never infer identity from token presence.
+
+const path = require('node:path');
+const fs = require('node:fs/promises');
+const state = require('../lib/url-preservation-state.js');
+const planLib = require('../lib/url-redirect-plan.js');
+const verification = require('../lib/url-verification.js');
+const reportLib = require('../lib/url-preservation-report.js');
+const importedTargets = require('../lib/imported-redirect-targets.js');
+const { readEnvFile } = require('../lib/config-env.js');
+
+function parseArgs(argv) {
+  const [mode, ...rest] = argv;
+  const args = { mode, flags: new Set() };
+  for (let i = 0; i < rest.length; i += 1) {
+    const token = rest[i];
+    if (['--exclusive-edit-window-confirmed', '--after-dns-switch'].includes(token)) args.flags.add(token);
+    else if (token.startsWith('--')) args[token.slice(2)] = rest[++i];
+    else throw new Error(`Unexpected argument: ${token}`);
+  }
+  if (!['sources', 'import-targets', 'report', 'plan', 'apply', 'verify', 'retire-import-plan'].includes(mode)) throw new Error('unsupported mode');
+  if (!args.project) throw new Error('--project <dir> is required');
+  args.project = path.resolve(args.project);
+  return args;
+}
+
+async function loadInputs(projectDir) {
+  // Replay all four import-era artifacts (latest row per key), so a recorded redirect
+  // requirement or unresolved/manual decision cannot drop out of the plan.
+  const ledger = await state.loadUrlLedger(projectDir);
+  const importRedirects = await state.loadRedirectsForPlanning(projectDir);
+  const importUnresolved = await state.loadUnresolved(projectDir);
+  const basePaths = await state.loadBasePaths(projectDir);
+  const sources = await state.loadSourceRedirects(projectDir);
+  const importedRedirectOutcomes = await importedTargets.currentAuditRows(projectDir);
+  return {
+    ledgerRows: Object.values(ledger.byKey),
+    importRedirects: Object.values(importRedirects.byKey),
+    invalidImportRedirects: importRedirects.rejected,
+    importUnresolved: Object.values(importUnresolved.byKey),
+    basePaths: basePaths.entries,
+    sourceRules: sources.latest,
+    importedRedirectOutcomes,
+    coverage: await state.loadStateJson(projectDir, 'sourceRedirectCoverage'),
+    sourceDomains: await state.loadStateJson(projectDir, 'sourceDomains'),
+    finalRoutes: await state.loadStateJson(projectDir, 'finalRoutes'),
+    launchPlan: await state.loadStateJson(projectDir, 'launchPlan'),
+    applyStatus: await state.loadStateJson(projectDir, 'applyStatus'),
+  };
+}
+
+function siteIdOf(inputs, env) {
+  return (inputs.finalRoutes && inputs.finalRoutes.siteId) || (inputs.launchPlan && inputs.launchPlan.siteId) || (env && env.WIX_SITE_ID) || 'unbound-site';
+}
+
+function readClientFrom(env) {
+  const { createWixClient } = require('../resources/rp-target-wix/lib/wix-writers.js');
+  const token = env.WIX_API_KEY || env.WIX_AUTH_TOKEN || env.WIX_REDIRECTS_APP_TOKEN;
+  if (!token || !env.WIX_SITE_ID) throw new Error('--wix-env needs WIX_SITE_ID and WIX_API_KEY or WIX_AUTH_TOKEN');
+  return createWixClient({ authToken: token, siteId: env.WIX_SITE_ID });
+}
+
+function writeCredentialFrom(env) {
+  if (env.WIX_REDIRECTS_APP_TOKEN) {
+    return { token: env.WIX_REDIRECTS_APP_TOKEN, siteId: env.WIX_REDIRECTS_APP_SITE_ID, identity: env.WIX_REDIRECTS_CREDENTIAL_IDENTITY };
+  }
+  if (env.WIX_AUTH_TOKEN && env.WIX_REDIRECTS_CREDENTIAL_IDENTITY === 'WIX_USER') {
+    return { token: env.WIX_AUTH_TOKEN, siteId: env.WIX_SITE_ID, identity: 'WIX_USER' };
+  }
+  return null;
+}
+
+async function writeReport(projectDir, plan, inputs) {
+  const execution = await state.loadRedirectExecution(projectDir);
+  const verified = await state.loadUrlVerification(projectDir);
+  const report = reportLib.buildUrlPreservationReport({
+    plan,
+    executionRows: execution.rows,
+    verificationRows: verified.rows,
+    launchPlan: inputs.launchPlan,
+    applyStatus: inputs.applyStatus && inputs.applyStatus.planDigest === plan.planDigest ? inputs.applyStatus : null,
+  });
+  const paths = await reportLib.writeUrlPreservationReport(projectDir, report);
+  await importedTargets.updateVerificationOutcomes(projectDir, plan, verified.rows);
+  return { report, paths, rejectedRows: execution.rejected.length + verified.rejected.length };
+}
+
+function summaryOf(report) {
+  return {
+    status: report.status,
+    counts: report.counts,
+    obligations: report.obligationCount,
+    remoteRules: report.remoteRuleCount,
+    coverageComplete: report.coverage.complete,
+    operatorActions: report.operatorActions.map((a) => ({ code: a.code, severity: a.severity, affectedCount: a.affectedCount })),
+    report: reportLib.REPORT_MD,
+  };
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const projectDir = args.project;
+  if (args.mode === 'retire-import-plan') {
+    if (!args['wix-env']) throw new Error('retire-import-plan needs --wix-env for a current destination inventory');
+    const env = await readEnvFile(path.resolve(args['wix-env']));
+    const seo = require('../resources/rp-target-wix/lib/seo-redirects.js');
+    const targetInventory = await seo.listWithBackoff(readClientFrom(env), {
+      sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+    });
+    const retired = await importedTargets.retireImportedPlan({ projectDir,
+      sourceStableKey: args['source-key'], sourceRelativeUrl: args.from,
+      targetRelativeUrl: args.to, evidence: args.evidence, targetInventory });
+    console.log(JSON.stringify(retired));
+    return;
+  }
+  if (args.mode === 'sources') {
+    const { extractRedirectSources } = require('../resources/rp-source-wordpress/lib/wp-redirect-sources.js');
+    const input = JSON.parse(await fs.readFile(path.resolve(args.input), 'utf8'));
+    const result = extractRedirectSources(input);
+    const capturedRules = result.rules.slice();
+    const existing = await state.loadSourceRedirects(projectDir);
+    const complete = result.coverage.providers.length > 0 &&
+      result.coverage.providers.every((row) => ['extracted', 'confirmed_empty'].includes(row.status));
+    if (complete) {
+      const present = new Set(result.rules.map((rule) => rule.ruleKey));
+      for (const prior of existing.latest) {
+        if (present.has(prior.ruleKey) || prior.disabledReason === 'removed_from_complete_capture') continue;
+        result.rules.push({ ...prior, enabled: false, disabledReason: 'removed_from_complete_capture',
+          extractedAt: result.coverage.generatedAt });
+      }
+    }
+    let appended = 0;
+    for (const rule of result.rules) {
+      const prior = existing.byKey[rule.ruleKey];
+      const same = prior && JSON.stringify({ ...prior, extractedAt: null }) === JSON.stringify({ ...rule, extractedAt: null });
+      if (!same) { await state.appendSourceRedirectRow(projectDir, rule); appended += 1; }
+    }
+    await state.writeStateJson(projectDir, 'sourceRedirectCoverage', result.coverage);
+    const sourceDomains = await state.loadStateJson(projectDir, 'sourceDomains');
+    if (sourceDomains) {
+      await importedTargets.planImportedRedirectTargets({ projectDir,
+        runId: args.run || input.runId || result.coverage.generatedAt,
+        captureRevision: result.coverage.generatedAt,
+        rules: importedTargets.adaptSourceRedirects(capturedRules, {
+          captureRevision: result.coverage.generatedAt, sourceDomains,
+        }), fullCapture: complete });
+    }
+    console.log(JSON.stringify({ rules: capturedRules.length, appended, coverage: result.coverage.providers.map((p) => ({ provider: p.provider, status: p.status, ruleCount: p.ruleCount })) }, null, 2));
+    return;
+  }
+
+  if (args.mode === 'import-targets') {
+    const sourceDomains = await state.loadStateJson(projectDir, 'sourceDomains');
+    const coverage = await state.loadStateJson(projectDir, 'sourceRedirectCoverage');
+    if (!sourceDomains || !coverage?.generatedAt) throw new Error('import-targets needs declared source domains and captured source redirect coverage');
+    const sourceRules = (await state.loadSourceRedirects(projectDir)).latest
+      .filter((rule) => rule.disabledReason !== 'removed_from_complete_capture');
+    const complete = coverage.providers.length > 0 &&
+      coverage.providers.every((row) => ['extracted', 'confirmed_empty'].includes(row.status));
+    const report = await importedTargets.planImportedRedirectTargets({ projectDir,
+      runId: args.run || coverage.generatedAt, captureRevision: coverage.generatedAt,
+      rules: importedTargets.adaptSourceRedirects(sourceRules, {
+        captureRevision: coverage.generatedAt, sourceDomains,
+      }), fullCapture: complete });
+    console.log(JSON.stringify({ captureComplete: report.captureComplete,
+      rules: report.rules.length, actionCount: report.operatorActions.length }));
+    return;
+  }
+
+  const inputs = await loadInputs(projectDir);
+  const env = args['wix-env'] ? await readEnvFile(path.resolve(args['wix-env'])) : null;
+  const siteId = siteIdOf(inputs, env);
+  let inventory = null;
+  let inventoryError = null;
+  let readClient = null;
+  if (env && (args.mode === 'plan' || args.mode === 'apply')) {
+    readClient = readClientFrom(env);
+    if (env.WIX_SITE_ID !== siteId) throw new Error('WIX_SITE_ID does not match the destination site in final-routes.json/launch-plan.json');
+    const seo = require('../resources/rp-target-wix/lib/seo-redirects.js');
+    try {
+      inventory = await seo.listWithBackoff(readClient, { sleep: (ms) => new Promise((r) => setTimeout(r, ms)) });
+    } catch (error) {
+      if (args.mode !== 'apply') throw error;
+      inventoryError = error;
+    }
+  }
+  const plan = planLib.planRedirects({ siteId, ...inputs, targetInventory: inventory });
+  if (args.mode !== 'plan' && inventory === null && !inventoryError) {
+    const earlier = await state.loadStateJson(projectDir, 'redirectPlan');
+    if (earlier?.planDigest === plan.planDigest) {
+      const setupByKey = new Map((earlier.obligations || []).filter((ob) => ob.externalSetup)
+        .map((ob) => [ob.obligationKey, ob.externalSetup]));
+      for (const obligation of plan.obligations) if (obligation.externalTarget) {
+        obligation.externalSetup = setupByKey.get(obligation.obligationKey) || null;
+      }
+    }
+  }
+  await state.writeStateJson(projectDir, 'redirectPlan', plan);
+
+  if (args.mode === 'apply') {
+    if (!env) throw new Error('apply needs --wix-env');
+    if (!plan.websiteBuilt) throw new Error('apply needs final-routes.json from the website build');
+    const seo = require('../resources/rp-target-wix/lib/seo-redirects.js');
+    const credential = writeCredentialFrom(env);
+    let writeClient = null;
+    if (!seo.credentialProblem(credential, plan.siteId)) {
+      const { createWixClient } = require('../resources/rp-target-wix/lib/wix-writers.js');
+      writeClient = createWixClient({ authToken: credential.token, siteId: credential.siteId });
+    }
+    const result = await seo.applyRedirectPlan({
+      projectDir,
+      plan,
+      readClient,
+      initialInventory: inventory,
+      initialInventoryError: inventoryError,
+      writeClient,
+      credential,
+      launchPlan: inputs.launchPlan,
+      exclusiveEditWindowConfirmed: args.flags.has('--exclusive-edit-window-confirmed'),
+      runId: args.run || `url-redirects-${Date.now()}`,
+    });
+    const applyStatus = { schemaVersion: 1, planDigest: plan.planDigest, recordedAt: new Date().toISOString(), summary: result.summary, operatorActions: result.operatorActions };
+    await state.writeStateJson(projectDir, 'applyStatus', applyStatus);
+    inputs.applyStatus = applyStatus;
+    const { report } = await writeReport(projectDir, plan, inputs);
+    console.log(JSON.stringify({ apply: result.summary, ...summaryOf(report) }, null, 2));
+    return;
+  }
+
+  if (args.mode === 'verify') {
+    const endpoint = args['connect-host']
+      ? { mode: 'connect_override', connectHost: args['connect-host'], connectPort: args['connect-port'] ? Number(args['connect-port']) : undefined }
+      : { mode: 'public' };
+    const result = await verification.verifyUrls({
+      projectDir,
+      plan,
+      sourceDomains: inputs.sourceDomains,
+      stage: args.stage,
+      endpoint,
+      afterDnsSwitch: args.flags.has('--after-dns-switch'),
+      concurrency: args.concurrency ? Number(args.concurrency) : undefined,
+      timeoutMs: args['timeout-ms'] ? Number(args['timeout-ms']) : undefined,
+      retryBudget: args.retries ? Number(args.retries) : undefined,
+      runId: args.run || `url-verify-${Date.now()}`,
+    });
+    const { report } = await writeReport(projectDir, plan, inputs);
+    console.log(JSON.stringify({ verify: result.summary, exceptionCount: result.exceptionCount, exceptions: result.exceptions, evidence: result.evidence, ...summaryOf(report) }, null, 2));
+    return;
+  }
+
+  const { report, rejectedRows } = await writeReport(projectDir, plan, inputs);
+  console.log(JSON.stringify({ ...summaryOf(report), rejectedStateRows: rejectedRows }, null, 2));
+}
+
+if (require.main === module) {
+  main().catch((error) => {
+    console.error(`url-redirects: ${error.message}`);
+    process.exit(1);
+  });
+}
+
+module.exports = { parseArgs, loadInputs, writeCredentialFrom };

package/skills/wix-replatform/scripts/user-action.js

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('node:fs/promises');
+const path = require('node:path');
+const {
+  createUserAction,
+  listUserActions,
+  readUserAction,
+  answerUserAction,
+} = require('../lib/user-actions.js');
+const { applyUserActionEffect } = require('../lib/user-action-effects.js');
+
+function parseArgs(argv) {
+  const result = { _: [] };
+  for (let index = 0; index < argv.length; index += 1) {
+    const value = argv[index];
+    if (!value.startsWith('--')) result._.push(value);
+    else {
+      const key = value.slice(2).replace(/-([a-z])/g, (_, letter) => letter.toUpperCase());
+      result[key] = key === 'acknowledge' ? true : argv[++index];
+    }
+  }
+  return result;
+}
+
+function applyEffect(projectDir, request, answer) {
+  return applyUserActionEffect(projectDir, request, answer);
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const command = args._[0];
+  if (!command || !args.project) throw new Error('Usage: user-action.js create|list|show|answer --project <path> ...');
+  const projectDir = path.resolve(args.project);
+  let result;
+  if (command === 'create') {
+    if (!args.requestFile) throw new Error('create requires --request-file <json>');
+    result = await createUserAction(projectDir, JSON.parse(await fs.readFile(path.resolve(args.requestFile), 'utf8')));
+  } else if (command === 'list') {
+    result = await listUserActions(projectDir, { status: args.status || null });
+  } else if (command === 'show') {
+    if (!args.request) throw new Error('show requires --request <id>');
+    result = await readUserAction(projectDir, args.request);
+  } else if (command === 'answer') {
+    if (!args.request) throw new Error('answer requires --request <id>');
+    const answer = args.acknowledge ? { acknowledged: true, ...(args.note ? { note: args.note } : {}) } : args.choice !== undefined ? { choice: args.choice, ...(args.note ? { note: args.note } : {}) } : { text: args.text };
+    result = await answerUserAction(projectDir, args.request, answer, {
+      applyEffect: (request, normalized) => applyEffect(projectDir, request, normalized),
+    });
+  } else throw new Error(`unknown command: ${command}`);
+  process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+}
+
+main().catch((error) => {
+  process.stderr.write(`${error && error.message ? error.message : error}\n`);
+  process.exit(2);
+});

package/skills/wix-replatform/scripts/website-handoff-generate.js

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+'use strict';
+
+const path = require('node:path');
+const { createProgressLogger, parseProgressArgs } = require('../lib/progress-log.js');
+const { generateWebsiteHandoff } = require('../lib/website-handoff.js');
+
+let progress;
+
+async function main() {
+  const parsed = parseProgressArgs(process.argv.slice(2));
+  progress = createProgressLogger({
+    script: 'skills/wix-replatform/scripts/website-handoff-generate.js',
+    ...parsed.progress,
+  });
+  progress.start('Website handoff generation started', { phase: 'orchestration', step: 'website-handoff' });
+
+  const projectDirArg = parsed.args[0];
+  if (!projectDirArg) {
+    console.error('Usage: node scripts/website-handoff-generate.js <projectDir> [--progress-log <path>]');
+    progress.error('Missing project directory', { phase: 'orchestration', step: 'website-handoff' });
+    process.exit(1);
+  }
+
+  const projectDir = path.resolve(projectDirArg);
+  const result = await generateWebsiteHandoff(projectDir);
+  const warnings = result.handoff.warnings || [];
+  console.log(JSON.stringify({
+    // The artifact is written even on failure; `ok` means generation produced no warnings.
+    ok: warnings.length === 0,
+    handoffPath: path.relative(projectDir, result.handoffPath).replace(/\\/g, '/'),
+    summaryPath: path.relative(projectDir, result.summaryPath).replace(/\\/g, '/'),
+    allowedNow: result.handoff.frontendPhase.allowedNow,
+    dynamicRouteCount: result.handoff.routeIntent.dynamicRoutes.length,
+    collectionCount: result.handoff.bindings.cmsCollections.length,
+    wixAppCount: result.handoff.bindings.wixApps.length,
+    ...(warnings.length ? { warnings } : {}),
+  }, null, 2));
+  if (warnings.length) {
+    progress.error('Website handoff generated with blocking warnings', {
+      phase: 'orchestration',
+      step: 'website-handoff',
+      artifact: projectDir,
+    });
+    process.exitCode = 1;
+    return;
+  }
+  progress.complete('Website handoff generation completed', {
+    phase: 'orchestration',
+    step: 'website-handoff',
+    artifact: projectDir,
+  });
+}
+
+main().catch((error) => {
+  if (progress) {
+    progress.error(error && error.message ? error.message : 'Website handoff generation failed', {
+      phase: 'orchestration',
+      step: 'website-handoff',
+    });
+  }
+  console.error(error && error.message ? error.message : error);
+  process.exit(1);
+});

package/skills/wix-replatform/scripts/wix-dashboard-url.js

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+'use strict';
+
+const { buildWixDashboardLink, buildWixDashboardUrl } = require('../lib/wix-dashboard-url.js');
+
+function parseArgs(argv) {
+  const options = { json: false, path: '' };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--json') {
+      options.json = true;
+    } else if (arg === '--path') {
+      i += 1;
+      options.path = argv[i] || '';
+    } else if (arg === '--meta-site-id' || arg === '--metasite-id' || arg === '--site-id') {
+      i += 1;
+      options.metaSiteId = argv[i];
+    } else if (!options.metaSiteId) {
+      options.metaSiteId = arg;
+    } else {
+      throw new Error(`Unexpected argument: ${arg}`);
+    }
+  }
+  return options;
+}
+
+function usage() {
+  return [
+    'Usage: node skills/wix-replatform/scripts/wix-dashboard-url.js <metaSiteId> [--json]',
+    '       node skills/wix-replatform/scripts/wix-dashboard-url.js --meta-site-id <metaSiteId> [--path <dashboard-path>] [--json]',
+  ].join('\n');
+}
+
+async function main() {
+  const options = parseArgs(process.argv.slice(2));
+  if (!options.metaSiteId) {
+    console.error(usage());
+    process.exit(1);
+  }
+
+  const link = options.path
+    ? {
+        ...buildWixDashboardLink(options.metaSiteId),
+        dashboardUrl: buildWixDashboardUrl(options.metaSiteId, { path: options.path }),
+      }
+    : buildWixDashboardLink(options.metaSiteId);
+
+  console.log(options.json ? JSON.stringify(link, null, 2) : link.dashboardUrl);
+}
+
+main().catch((error) => {
+  console.error(error && error.message ? error.message : error);
+  process.exit(1);
+});

package/skills/wix-replatform/scripts/wix-destination.js

@@ -0,0 +1,143 @@
+#!/usr/bin/env node
+'use strict';
+
+// Deterministic destination coordinator CLI. rp-destination runs this instead of
+// composing creation requests itself. It prints a JSON outcome (never credentials) and exits
+// 0 when the destination is ready, 3 when a durable user action is waiting, 4 when blocked.
+const crypto = require('node:crypto');
+const fs = require('node:fs/promises');
+const os = require('node:os');
+const path = require('node:path');
+const { execFile, spawn } = require('node:child_process');
+const { promisify } = require('node:util');
+
+const { ensureDestination } = require('../lib/destination.js');
+const { realClock } = require('../lib/destination-http.js');
+const { buildWixDashboardUrl } = require('../lib/wix-dashboard-url.js');
+
+const execFileAsync = promisify(execFile);
+const CLI = ['@wix/cli@latest'];
+
+function usage() {
+  return [
+    'Usage:',
+    '  node scripts/wix-destination.js ensure --project-dir <dir>',
+    '',
+    'Resolves the one destination for a new-site migration: asks for the site type when it is',
+    'missing, delegates Headless to wix-headless-scaffold.js, creates a Studio/Harmony site',
+    'through the API, verifies its editor and that it is unpublished, and records',
+    'orchestration/destination.json. Never publishes, unpublishes or deletes a site, and never',
+    'repeats a create whose outcome is unknown.',
+  ].join('\n');
+}
+
+// Credentials come from the operator's existing Wix CLI login. Values stay in memory only.
+async function cliToken(args) {
+  const { stdout } = await execFileAsync('npx', [...CLI, 'token', ...args], { timeout: 60_000, maxBuffer: 1024 * 1024 });
+  const token = String(stdout || '').trim().split(/\r?\n/).pop();
+  return token || null;
+}
+
+function defaultCredentials() {
+  return {
+    async identity() {
+      try {
+        const { stdout } = await execFileAsync('npx', [...CLI, 'whoami'], { timeout: 30_000, maxBuffer: 1024 * 1024 });
+        const identity = String(stdout || '').trim();
+        return { authenticated: Boolean(identity), identity: identity || null };
+      } catch {
+        return { authenticated: false, identity: null };
+      }
+    },
+    // The login's user id, which the creation response's metaSite.ownerId must match. `wix
+    // whoami` prints only an email, so it is read from the CLI's own login record (the same
+    // source rp-telemetry uses); a missing or unreadable record fails before any create.
+    async userId() {
+      try {
+        const raw = await fs.readFile(path.join(os.homedir(), '.wix', 'auth', 'account.json'), 'utf8');
+        const value = JSON.parse(raw)?.userInfo?.userId;
+        return typeof value === 'string' && value ? value : null;
+      } catch {
+        return null;
+      }
+    },
+    accountToken: () => cliToken([]),
+    siteToken: (metaSiteId) => cliToken(['--site', metaSiteId]),
+  };
+}
+
+function defaultHeadless({ projectDir, businessName }) {
+  return new Promise((resolve) => {
+    const child = spawn(process.execPath, [path.join(__dirname, 'wix-headless-scaffold.js'), '--business-name', businessName, '--project-dir', projectDir], {
+      stdio: ['ignore', 'inherit', 'pipe'],
+    });
+    let stderr = '';
+    child.stderr.on('data', (chunk) => { stderr = `${stderr}${chunk}`.slice(-2000); process.stderr.write(chunk); });
+    child.on('close', (code) => resolve({ ok: code === 0, message: code === 0 ? null : stderr.trim().split(/\r?\n/).pop() }));
+  });
+}
+
+function defaultDeps() {
+  return {
+    fetch: globalThis.fetch,
+    clock: realClock(),
+    credentials: defaultCredentials(),
+    headless: defaultHeadless,
+    randomUUID: () => crypto.randomUUID(),
+  };
+}
+
+function exitCodeFor(outcome) {
+  if (['verified', 'created', 'existing_destination', 'not_new_site'].includes(outcome)) return 0;
+  if (['awaiting_site_type', 'awaiting_editor_website_decision', 'awaiting_account_confirmation', 'awaiting_recovery', 'failed_before_create', 'ambiguous'].includes(outcome)) return 3;
+  if (outcome === 'blocked' || outcome === 'locked') return 4;
+  return 1;
+}
+
+// The printed summary omits nothing an operator needs and contains no credential.
+function summarize(result) {
+  const receipt = result.receipt || null;
+  return {
+    outcome: result.outcome,
+    ...(result.reason ? { reason: result.reason } : {}),
+    ...(result.errors ? { errors: result.errors } : {}),
+    ...(result.requestId ? { requestId: result.requestId } : {}),
+    ...(receipt ? {
+      status: receipt.status,
+      siteType: receipt.requestedSiteType,
+      creationMethod: receipt.creationMethod,
+      metaSiteId: receipt.metaSiteId,
+      observedEditorType: receipt.observedEditorType,
+      editorUrl: receipt.editorUrl,
+      publication: receipt.publication ? receipt.publication.state : null,
+      error: receipt.error,
+      recoveryRequestId: receipt.recovery ? receipt.recovery.requestId : null,
+      dashboardUrl: receipt.metaSiteId ? buildWixDashboardUrl(receipt.metaSiteId) : null,
+    } : {}),
+  };
+}
+
+async function main(argv = process.argv.slice(2), deps = defaultDeps()) {
+  const command = argv[0];
+  if (!command || command === '--help' || command === 'help') {
+    console.log(usage());
+    return command ? 0 : 1;
+  }
+  const index = argv.indexOf('--project-dir');
+  if (command !== 'ensure' || index === -1 || !argv[index + 1]) {
+    console.error(usage());
+    return 1;
+  }
+  const result = await ensureDestination(path.resolve(argv[index + 1]), deps);
+  process.stdout.write(`${JSON.stringify(summarize(result), null, 2)}\n`);
+  return exitCodeFor(result.outcome);
+}
+
+if (require.main === module) {
+  main().then((code) => { process.exitCode = code; }).catch((error) => {
+    console.error(error && error.message ? error.message : error);
+    process.exitCode = 1;
+  });
+}
+
+module.exports = { defaultDeps, exitCodeFor, main, summarize };