@wix/agent-skills 1.15.0 → 1.16.0

package/skills/wix-replatform/resources/rp-telemetry/scripts/meter-from-audit.js

@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+'use strict';
+
+// Derive MEASURED api_ms / api_calls / api_retries from a generated import's audit log, and emit
+// them as a `meter` call. This exists so the API half of the latency split is populated
+// mechanically rather than depending on anyone remembering to report it.
+//
+//   node scripts/meter-from-audit.js --project <migration dir> [--stage import] [--dry-run]
+//
+// TRAP this deliberately handles: a bulk write logs ONE audit row PER ITEM, each carrying the
+// BATCH's total latency. Summing `latencyMs` across rows therefore multiplies one call's latency by
+// its item count — on a real run that turned 346s of elapsed import into 1,050,992ms of "API time",
+// three times longer than the stage existed. Rows are collapsed per distinct
+// (runId, endpoint, batch, latencyMs) so a batch counts once, while genuinely separate calls
+// (category creates, link calls) each count individually.
+
+const fs = require('node:fs');
+const path = require('node:path');
+const recorder = require('../lib/telemetry-recorder.js');
+
+function parseArgs(argv) {
+  const args = { project: process.cwd(), stage: 'import', auditFile: null, dryRun: false };
+  for (let i = 0; i < argv.length; i += 1) {
+    if (argv[i] === '--project') { args.project = argv[i + 1]; i += 1; }
+    else if (argv[i] === '--stage') { args.stage = argv[i + 1]; i += 1; }
+    else if (argv[i] === '--audit') { args.auditFile = argv[i + 1]; i += 1; }
+    else if (argv[i] === '--dry-run') args.dryRun = true;
+  }
+  return args;
+}
+
+function deriveFromAudit(records) {
+  const calls = new Map();
+  let retries = 0;
+  for (const row of records) {
+    if (typeof row.latencyMs !== 'number') continue;
+    // `batch` present => a bulk call fanned out across one row per item. Collapse on the batch's
+    // identity PLUS the latency, because a single logical batch number can cover more than one
+    // physical request (a contract probe followed by the remainder).
+    const key = row.batch === undefined
+      ? `single|${row.runId}|${row.endpoint || row.operation}|${row.ts}`
+      : `bulk|${row.runId}|${row.endpoint || row.operation}|${row.batch}|${row.latencyMs}`;
+    if (!calls.has(key)) calls.set(key, row.latencyMs);
+    if (typeof row.retryCount === 'number') retries += row.retryCount;
+  }
+  const apiMs = [...calls.values()].reduce((sum, ms) => sum + ms, 0);
+  return { api_ms: Math.round(apiMs), api_calls: calls.size, api_retries: retries };
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const auditFile = args.auditFile || path.join(args.project, 'logs', 'import-audit.ndjson');
+  if (!fs.existsSync(auditFile)) {
+    process.stdout.write(`${JSON.stringify({ ok: false, errors: [`audit log not found: ${auditFile}`] })}\n`);
+    process.exit(1);
+  }
+  const records = fs
+    .readFileSync(auditFile, 'utf8')
+    .split('\n')
+    .filter(Boolean)
+    .map((line) => { try { return JSON.parse(line); } catch { return null; } })
+    .filter(Boolean);
+
+  const derived = deriveFromAudit(records);
+  if (args.dryRun) {
+    process.stdout.write(`${JSON.stringify({ ok: true, dryRun: true, auditRecords: records.length, ...derived })}\n`);
+    return;
+  }
+  const result = recorder.meter(args.project, { ...derived, stage: args.stage });
+  process.stdout.write(`${JSON.stringify({ ok: true, auditRecords: records.length, ...derived, ...result })}\n`);
+}
+
+if (require.main === module) {
+  try {
+    main();
+  } catch (error) {
+    const errors = error instanceof recorder.ValidationError ? error.errors : [error.message || String(error)];
+    process.stdout.write(`${JSON.stringify({ ok: false, errors })}\n`);
+    process.exit(1);
+  }
+}
+
+module.exports = { deriveFromAudit };

package/skills/wix-replatform/resources/rp-telemetry/scripts/rp-telemetry.js

@@ -0,0 +1,141 @@
+#!/usr/bin/env node
+'use strict';
+
+// CLI for the RePlatform run-telemetry recorder. The rp-telemetry companion
+// skill invokes this via bash; the agent never hand-writes the signal layer.
+//
+// Usage (run against the active migration project via --project or cwd):
+//   node scripts/rp-telemetry.js start '<dims-json>' [--project <dir>]
+//   node scripts/rp-telemetry.js dims '<dims-json>'
+//   node scripts/rp-telemetry.js record '<event-json>'
+//   node scripts/rp-telemetry.js stage start <stage>
+//   node scripts/rp-telemetry.js stage end <stage> [--outcome <outcome>]
+//   node scripts/rp-telemetry.js meter --api-ms 1234 --api-calls 73 [--stage <stage>]
+//   node scripts/rp-telemetry.js meter '{"model_ms":42000,"output_tokens":18000}'
+//   node scripts/rp-telemetry.js wait start [--halt <subtype> --skill <s> [--what '<text>']]
+//   node scripts/rp-telemetry.js wait end
+//   node scripts/rp-telemetry.js finalize '<rollup-json>'
+//   node scripts/rp-telemetry.js rebuild [--attempt <n>] [--push]
+//   node scripts/rp-telemetry.js status
+//
+// Output: one JSON object on stdout. {"ok":true,...} on success; on rejection
+// {"ok":false,"errors":[...],"hint":...} with exit code 1 — fix and retry.
+
+const fs = require('node:fs');
+const recorder = require('../lib/telemetry-recorder.js');
+
+const VALUE_FLAGS = new Set(['--project', '--outcome', '--halt', '--skill', '--what', '--attempt', '--stage']);
+// Meter measurements are accepted as kebab-case flags so a shell script can report its own timing
+// without composing JSON: --api-ms 1234 --api-calls 73.
+const METER_FLAGS = new Map(
+  ['model_ms', 'api_ms', 'script_ms', 'input_tokens', 'output_tokens', 'cache_read_tokens', 'cache_write_tokens', 'api_calls', 'api_retries']
+    .map((key) => [`--${key.replace(/_/g, '-')}`, key]),
+);
+
+function parseArgs(argv) {
+  const positional = [];
+  const flags = {};
+  const meter = {};
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (VALUE_FLAGS.has(arg)) {
+      flags[arg.slice(2)] = argv[i + 1];
+      i += 1;
+    } else if (METER_FLAGS.has(arg)) {
+      const raw = argv[i + 1];
+      const value = Number(raw);
+      if (!Number.isFinite(value)) fail([`${arg} expects a number (got: ${raw === undefined ? '(none)' : raw})`]);
+      meter[METER_FLAGS.get(arg)] = value;
+      i += 1;
+    } else if (arg === '--push') {
+      flags.push = true;
+    } else if (arg.startsWith('--')) {
+      fail([`unknown flag: ${arg}`]);
+    } else {
+      positional.push(arg);
+    }
+  }
+  return { positional, flags, meter };
+}
+
+function fail(errors, hint) {
+  process.stdout.write(`${JSON.stringify({ ok: false, errors, ...(hint ? { hint } : {}) })}\n`);
+  process.exit(1);
+}
+
+function parseJsonArg(raw, label) {
+  if (raw === undefined) fail([`missing ${label} JSON argument`]);
+  try {
+    return JSON.parse(raw);
+  } catch (error) {
+    fail([`${label} is not valid JSON: ${error.message}`]);
+  }
+  return undefined;
+}
+
+async function main() {
+  const { positional, flags, meter } = parseArgs(process.argv.slice(2));
+  const [command, ...rest] = positional;
+  const projectDir = flags.project || process.cwd();
+  if (!fs.existsSync(projectDir) || !fs.statSync(projectDir).isDirectory()) {
+    fail([`project directory not found: ${projectDir}`], 'pass --project <migration project dir>');
+  }
+
+  let result;
+  switch (command) {
+    case 'start':
+      result = await recorder.start(projectDir, rest[0] === undefined ? {} : parseJsonArg(rest[0], 'dims'));
+      break;
+    case 'dims':
+      result = await recorder.dims(projectDir, parseJsonArg(rest[0], 'dims'));
+      break;
+    case 'record':
+      result = await recorder.record(projectDir, parseJsonArg(rest[0], 'event'));
+      break;
+    case 'stage':
+      result = recorder.stage(projectDir, rest[0], rest[1], { outcome: flags.outcome });
+      break;
+    case 'meter': {
+      // Flags and a JSON payload both work; flags win on conflict so a wrapper script can override
+      // a template payload without rebuilding the JSON.
+      const fromJson = rest[0] === undefined ? {} : parseJsonArg(rest[0], 'meter');
+      const payload = { ...fromJson, ...meter };
+      if (flags.stage) payload.stage = flags.stage;
+      result = recorder.meter(projectDir, payload);
+      break;
+    }
+    case 'wait':
+      result = await recorder.wait(projectDir, rest[0], {
+        haltSubtype: flags.halt,
+        skill: flags.skill,
+        what: flags.what,
+      });
+      break;
+    case 'finalize':
+      result = await recorder.finalize(projectDir, parseJsonArg(rest[0], 'rollup'));
+      break;
+    case 'rebuild':
+      result = await recorder.rebuild(projectDir, {
+        attempt: flags.attempt === undefined ? undefined : Number(flags.attempt),
+        push: flags.push === true,
+      });
+      break;
+    case 'status':
+      result = recorder.status(projectDir);
+      break;
+    default:
+      fail(
+        [`unknown command: ${command || '(none)'}`],
+        'commands: start, dims, record, stage start|end, meter, wait start|end, finalize, rebuild, status',
+      );
+      return;
+  }
+  process.stdout.write(`${JSON.stringify({ ok: true, ...result })}\n`);
+}
+
+main().catch((error) => {
+  if (error instanceof recorder.ValidationError) {
+    fail(error.errors, error.hint || undefined);
+  }
+  fail([error && error.message ? error.message : String(error)]);
+});

package/skills/wix-replatform/scripts/artifact-freshness.js

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+'use strict';
+
+const path = require('node:path');
+const {
+  createFreshnessMetadata,
+  validateImportPlanFreshness,
+  writeFreshnessMetadata,
+  writeImportPlanDelta,
+} = require('../lib/artifact-freshness.js');
+
+function parseArgs(argv) {
+  const args = { _: [] };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg.startsWith('--')) {
+      const key = arg.slice(2).replace(/-([a-z])/g, (_, char) => char.toUpperCase());
+      const next = argv[i + 1];
+      if (!next || next.startsWith('--')) {
+        args[key] = true;
+      } else {
+        args[key] = next;
+        i += 1;
+      }
+    } else {
+      args._.push(arg);
+    }
+  }
+  return args;
+}
+
+function usage() {
+  return [
+    'Usage:',
+    '  node scripts/artifact-freshness.js write <projectDir> --domains-dir <domainsDir> [--metadata <path>]',
+    '  node scripts/artifact-freshness.js check <projectDir> --domains-dir <domainsDir> [--metadata <path>] [--delta <path>]',
+  ].join('\n');
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const command = args._[0];
+  const projectDir = args._[1] ? path.resolve(args._[1]) : null;
+  if (args.help) {
+    process.stderr.write(`${usage()}\n`);
+    process.exit(0);
+  }
+  if (!command || !projectDir || args.help) {
+    process.stderr.write(`${usage()}\n`);
+    process.exit(1);
+  }
+  const domainsDir = args.domainsDir ? path.resolve(args.domainsDir) : null;
+  const metadataPath = args.metadata || 'execution/review/import-plan.freshness.json';
+  if (command === 'write') {
+    const metadata = createFreshnessMetadata({ projectDir, domainsDir });
+    writeFreshnessMetadata(path.resolve(projectDir, metadataPath), metadata);
+    process.stdout.write(`${JSON.stringify({ ok: true, metadataPath }, null, 2)}\n`);
+    return;
+  }
+  if (command === 'check') {
+    const result = validateImportPlanFreshness({ projectDir, domainsDir, metadataPath });
+    if (!result.ok && args.delta) {
+      writeImportPlanDelta(path.resolve(projectDir, args.delta), result);
+    }
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+    process.exit(result.ok ? 0 : 1);
+  }
+  throw new Error(`Unknown command: ${command}\n${usage()}`);
+}
+
+try {
+  main();
+} catch (error) {
+  process.stderr.write(`${error.message}\n`);
+  process.exit(1);
+}

package/skills/wix-replatform/scripts/execution-manifest-validate.js

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('node:fs/promises');
+const path = require('node:path');
+const { validateManifest } = require('../lib/execution-manifest.js');
+const { createProgressLogger, parseProgressArgs } = require('../lib/progress-log.js');
+
+let progress;
+
+async function main() {
+  const parsed = parseProgressArgs(process.argv.slice(2));
+  progress = createProgressLogger({
+    script: 'skills/replatform/scripts/execution-manifest-validate.js',
+    ...parsed.progress,
+  });
+  progress.start('Execution manifest validation started', { phase: 'validation' });
+
+  const manifestPathArg = parsed.args[0];
+  if (!manifestPathArg) {
+    console.error('Usage: node scripts/execution-manifest-validate.js <manifestPath> [--progress-log <path>]');
+    progress.error('Missing manifest path', { phase: 'validation' });
+    process.exit(1);
+  }
+  const manifestPath = path.resolve(manifestPathArg);
+  const manifest = JSON.parse(await fs.readFile(manifestPath, 'utf8'));
+  const result = validateManifest(manifest);
+  console.log(JSON.stringify(result, null, 2));
+  if (result.ok) {
+    progress.complete('Execution manifest validation completed', { phase: 'validation', artifact: manifestPath });
+  } else {
+    progress.error('Execution manifest validation failed', { phase: 'validation', artifact: manifestPath, count: result.errors.length, unit: 'errors' });
+  }
+  process.exit(result.ok ? 0 : 1);
+}
+
+main().catch((error) => {
+  if (progress) {
+    progress.error(error && error.message ? error.message : 'Execution manifest validation failed', { phase: 'validation' });
+  }
+  console.error(error && error.message ? error.message : error);
+  process.exit(1);
+});

package/skills/wix-replatform/scripts/execution-state-prepare.js

@@ -0,0 +1,128 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('node:fs/promises');
+const path = require('node:path');
+const { prepareExecutionState } = require('../lib/execution-state.js');
+const { createProgressLogger, parseProgressArgs } = require('../lib/progress-log.js');
+
+let progress;
+
+function usage() {
+  console.error(`Usage:
+  node scripts/execution-state-prepare.js <projectDir> [--manifest <path>] [--cms-mirror-file <taskId:path>] [--progress-log <path>]
+
+CMS mirror files may be NDJSON or JSON arrays of crosswalk rows. Use one --cms-mirror-file
+per import task that has cmsMirror.mode download/download-and-upload.
+`);
+}
+
+function parseArgs(argv) {
+  const args = { cmsMirrorFiles: [] };
+  for (let i = 0; i < argv.length; i += 1) {
+    const token = argv[i];
+    if (token === '--manifest') {
+      args.manifest = argv[i + 1];
+      i += 1;
+    } else if (token === '--cms-mirror-file') {
+      args.cmsMirrorFiles.push(argv[i + 1]);
+      i += 1;
+    } else if (!args.projectDir) {
+      args.projectDir = token;
+    } else {
+      throw new Error(`unknown argument: ${token}`);
+    }
+  }
+  return args;
+}
+
+async function readRows(filePath) {
+  const raw = await fs.readFile(filePath, 'utf8');
+  const trimmed = raw.trim();
+  if (!trimmed) {
+    return [];
+  }
+  if (trimmed.startsWith('[')) {
+    const parsed = JSON.parse(trimmed);
+    if (!Array.isArray(parsed)) {
+      throw new Error(`${filePath} must contain a JSON array when using JSON format`);
+    }
+    return parsed;
+  }
+  return trimmed.split(/\r?\n/).filter(Boolean).map((line, index) => {
+    try {
+      return JSON.parse(line);
+    } catch (error) {
+      throw new Error(`${filePath}:${index + 1} invalid NDJSON: ${error.message}`);
+    }
+  });
+}
+
+async function readMirrorRows(projectDir, specs) {
+  const rowsByTaskId = {};
+  for (const spec of specs) {
+    const separator = spec.indexOf(':');
+    if (separator <= 0) {
+      throw new Error(`--cms-mirror-file must be <taskId:path>, got: ${spec}`);
+    }
+    const taskId = spec.slice(0, separator);
+    const filePath = path.resolve(projectDir, spec.slice(separator + 1));
+    rowsByTaskId[taskId] = await readRows(filePath);
+  }
+  return rowsByTaskId;
+}
+
+async function main() {
+  const parsed = parseProgressArgs(process.argv.slice(2));
+  progress = createProgressLogger({
+    script: 'skills/replatform/scripts/execution-state-prepare.js',
+    ...parsed.progress,
+  });
+  progress.start('Execution state preparation started', { phase: 'execution', step: 'prepare-state' });
+
+  const args = parseArgs(parsed.args);
+  if (!args.projectDir) {
+    usage();
+    progress.error('Missing project directory', { phase: 'execution', step: 'prepare-state' });
+    process.exit(1);
+  }
+
+  const projectDir = path.resolve(args.projectDir);
+  const manifestPath = args.manifest
+    ? path.resolve(projectDir, args.manifest)
+    : path.join(projectDir, 'execution', 'execution-manifest.json');
+  const manifest = JSON.parse(await fs.readFile(manifestPath, 'utf8'));
+  const cmsMirrorRowsByTaskId = await readMirrorRows(projectDir, args.cmsMirrorFiles);
+
+  const result = await prepareExecutionState(projectDir, manifest, { cmsMirrorRowsByTaskId });
+  console.log(JSON.stringify(result, null, 2));
+  if (result.ok) {
+    progress.complete('Execution state preparation completed', {
+      phase: 'execution',
+      step: 'prepare-state',
+      artifact: projectDir,
+      count: result.actions.length,
+      unit: 'actions',
+    });
+  } else {
+    progress.error('Execution state preparation blocked', {
+      phase: 'execution',
+      step: 'prepare-state',
+      artifact: projectDir,
+      count: result.errors.length,
+      unit: 'errors',
+    });
+  }
+  process.exit(result.ok ? 0 : 1);
+}
+
+main().catch((error) => {
+  if (progress) {
+    progress.error(error && error.message ? error.message : 'Execution state preparation failed', {
+      phase: 'execution',
+      step: 'prepare-state',
+    });
+  }
+  console.error(error && error.message ? error.message : error);
+  process.exit(1);
+});

package/skills/wix-replatform/scripts/orchestration-preflight.js

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+'use strict';
+
+const path = require('node:path');
+const { loadArtifacts, writeJsonAtomic } = require('../lib/orchestration-state.js');
+const { runPreflight } = require('../lib/orchestration-preflight.js');
+const { createProgressLogger, parseProgressArgs } = require('../lib/progress-log.js');
+
+let progress;
+
+async function main() {
+  const parsed = parseProgressArgs(process.argv.slice(2));
+  progress = createProgressLogger({
+    script: 'skills/replatform/scripts/orchestration-preflight.js',
+    ...parsed.progress,
+  });
+  progress.start('Orchestration preflight started', { phase: 'preflight' });
+
+  const projectDirArg = parsed.args[0];
+  if (!projectDirArg) {
+    console.error('Usage: node scripts/orchestration-preflight.js <projectDir> [--progress-log <path>]');
+    progress.error('Missing project directory', { phase: 'preflight' });
+    process.exit(1);
+  }
+  const projectDir = path.resolve(projectDirArg);
+  const artifacts = await loadArtifacts(projectDir);
+  if (!artifacts.run) {
+    throw new Error(`orchestration artifacts not initialized under ${projectDir}`);
+  }
+
+  const result = await runPreflight(projectDir, artifacts, { progress });
+  await writeJsonAtomic(path.join(projectDir, 'orchestration', 'preflight.json'), result);
+  console.log(JSON.stringify(result, null, 2));
+  if (result.status === 'pass') {
+    progress.complete('Orchestration preflight completed', { phase: 'preflight', artifact: projectDir });
+  } else {
+    progress.error('Orchestration preflight did not pass', { phase: 'preflight', artifact: projectDir, status: result.status });
+  }
+  process.exit(result.status === 'pass' ? 0 : 1);
+}
+
+main().catch((error) => {
+  if (progress) {
+    progress.error(error && error.message ? error.message : 'Orchestration preflight failed', { phase: 'preflight' });
+  }
+  console.error(error && error.message ? error.message : error);
+  process.exit(1);
+});

package/skills/wix-replatform/scripts/orchestration-route.js

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+'use strict';
+
+const path = require('node:path');
+const { loadArtifacts } = require('../lib/orchestration-state.js');
+const { determineNextStep } = require('../lib/orchestration-router.js');
+const { createProgressLogger, parseProgressArgs } = require('../lib/progress-log.js');
+
+let progress;
+
+async function main() {
+  const parsed = parseProgressArgs(process.argv.slice(2));
+  progress = createProgressLogger({
+    script: 'skills/replatform/scripts/orchestration-route.js',
+    ...parsed.progress,
+  });
+  progress.start('Orchestration route started', { phase: 'orchestration' });
+
+  const projectDirArg = parsed.args[0];
+  if (!projectDirArg) {
+    console.error('Usage: node scripts/orchestration-route.js <projectDir> [--progress-log <path>]');
+    progress.error('Missing project directory', { phase: 'orchestration' });
+    process.exit(1);
+  }
+  const projectDir = path.resolve(projectDirArg);
+  const artifacts = await loadArtifacts(projectDir);
+  if (!artifacts.run) {
+    throw new Error(`orchestration artifacts not initialized under ${projectDir}`);
+  }
+  const result = await determineNextStep(projectDir, artifacts);
+  console.log(JSON.stringify(result, null, 2));
+  if (result.ok) {
+    progress.complete('Orchestration route completed', { phase: 'orchestration', artifact: projectDir });
+  } else {
+    progress.error('Orchestration route failed', { phase: 'orchestration', artifact: projectDir });
+  }
+  process.exit(result.ok ? 0 : 1);
+}
+
+main().catch((error) => {
+  if (progress) {
+    progress.error(error && error.message ? error.message : 'Orchestration route failed', { phase: 'orchestration' });
+  }
+  console.error(error && error.message ? error.message : error);
+  process.exit(1);
+});