@wix/agent-skills 1.15.0 → 1.16.0

package/skills/wix-replatform/lib/progress-log.sh

@@ -0,0 +1,140 @@
+#!/usr/bin/env bash
+
+progress_log_path="${PROGRESS_LOG:-}"
+progress_run_id="${RUN_ID:-}"
+progress_parent_run_id="${PARENT_RUN_ID:-}"
+progress_script="${PROGRESS_SCRIPT:-${0#"$PWD"/}}"
+progress_seq=0
+progress_seq_state=""
+progress_started=0
+progress_terminal=0
+progress_heartbeat_pid=""
+progress_heartbeat_message="Still running"
+
+progress_slugify() {
+  printf '%s' "$1" | tr '[:upper:]' '[:lower:]' | sed -E 's/[^a-z0-9]+/-/g; s/^-+//; s/-+$//'
+}
+
+progress_init() {
+  if [[ -z "$progress_run_id" ]]; then
+    local slug
+    slug="$(progress_slugify "$progress_script")"
+    [[ -n "$slug" ]] || slug="script"
+    progress_run_id="${slug}-$(date +%s)-$(od -An -N2 -tx1 /dev/urandom | tr -d ' \n')"
+  fi
+  if [[ -z "$progress_seq_state" ]]; then
+    progress_seq_state="${TMPDIR:-/tmp}/rp-progress-${progress_run_id}.seq"
+  fi
+}
+
+progress_json_escape() {
+  local value="${1:-}"
+  value="${value//\\/\\\\}"
+  value="${value//\"/\\\"}"
+  value="${value//$'\n'/\\n}"
+  value="${value//$'\r'/\\r}"
+  value="${value//$'\t'/\\t}"
+  printf '%s' "$value"
+}
+
+progress_status_for_event() {
+  case "$1" in
+    complete) printf 'completed' ;;
+    error) printf 'failed' ;;
+    start|progress|heartbeat|warning) printf 'running' ;;
+    *) printf 'running' ;;
+  esac
+}
+
+progress_next_seq() {
+  progress_init
+  local lock="${progress_seq_state}.lock"
+  while ! mkdir "$lock" 2>/dev/null; do
+    sleep 0.05
+  done
+  local current=0
+  if [[ -f "$progress_seq_state" ]]; then
+    current="$(cat "$progress_seq_state")"
+  fi
+  progress_seq=$((current + 1))
+  printf '%s\n' "$progress_seq" > "$progress_seq_state"
+  rmdir "$lock"
+}
+
+progress_write() {
+  local event="$1"
+  local message="$2"
+  local fields="${3:-}"
+  [[ -n "$progress_log_path" ]] || return 0
+  progress_init
+  mkdir -p "$(dirname "$progress_log_path")"
+  progress_next_seq
+  local status ts line
+  status="$(progress_status_for_event "$event")"
+  ts="$(date -u +"%Y-%m-%dT%H:%M:%SZ")"
+  line="{\"ts\":\"$ts\",\"runId\":\"$(progress_json_escape "$progress_run_id")\""
+  if [[ -n "$progress_parent_run_id" ]]; then
+    line="$line,\"parentRunId\":\"$(progress_json_escape "$progress_parent_run_id")\""
+  fi
+  line="$line,\"script\":\"$(progress_json_escape "$progress_script")\",\"event\":\"$event\",\"status\":\"$status\",\"seq\":$progress_seq"
+  if [[ -n "$fields" ]]; then
+    line="$line,$fields"
+  fi
+  line="$line,\"message\":\"$(progress_json_escape "$message")\"}"
+  printf '%s\n' "$line" >> "$progress_log_path"
+  [[ "$event" == "start" ]] && progress_started=1
+  if [[ "$event" == "complete" || "$event" == "error" ]]; then
+    progress_terminal=1
+    progress_heartbeat_stop
+  fi
+}
+
+progress_start() { progress_write start "$1" "${2:-}"; }
+progress_progress() { progress_write progress "$1" "${2:-}"; }
+progress_heartbeat_line() { progress_write heartbeat "${1:-$progress_heartbeat_message}" "${2:-}"; }
+progress_warn() { progress_write warning "$1" "${2:-}"; }
+progress_error() { progress_write error "$1" "${2:-}"; }
+progress_complete() { progress_write complete "$1" "${2:-}"; }
+
+progress_heartbeat_start() {
+  local interval="${1:-30}"
+  progress_heartbeat_message="${2:-Still running}"
+  [[ -n "$progress_log_path" ]] || return 0
+  if [[ -n "$progress_heartbeat_pid" ]]; then
+    progress_error "heartbeat already active"
+    return 1
+  fi
+  (
+    while sleep "$interval"; do
+      progress_heartbeat_line "$progress_heartbeat_message"
+    done
+  ) &
+  progress_heartbeat_pid="$!"
+}
+
+progress_heartbeat_stop() {
+  if [[ -n "${progress_heartbeat_pid:-}" ]]; then
+    kill "$progress_heartbeat_pid" 2>/dev/null || true
+    wait "$progress_heartbeat_pid" 2>/dev/null || true
+    progress_heartbeat_pid=""
+  fi
+}
+
+progress_child_env() {
+  progress_init
+  if [[ -n "$progress_log_path" ]]; then
+    printf 'PROGRESS_LOG=%q PARENT_RUN_ID=%q ' "$progress_log_path" "$progress_run_id"
+  fi
+}
+
+progress_on_exit() {
+  local code=$?
+  progress_heartbeat_stop
+  if [[ "$progress_started" == "1" && "$progress_terminal" == "0" && "$code" != "0" ]]; then
+    progress_error "Process exited before writing a terminal progress record" "\"exitCode\":$code"
+  fi
+}
+
+trap progress_on_exit EXIT
+trap 'progress_heartbeat_stop; exit 130' INT
+trap 'progress_heartbeat_stop; exit 143' TERM

package/skills/wix-replatform/lib/url-preservation-state.js

@@ -0,0 +1,391 @@
+'use strict';
+
+const fs = require('node:fs/promises');
+const path = require('node:path');
+
+const SCHEMA_VERSION = 1;
+
+const URL_STATUS = new Set([
+  'preserved',
+  'redirect_required',
+  'pending_target_route',
+  'source_url_missing',
+  'target_url_missing',
+  'not_public',
+  'manual_review',
+]);
+const UNRESOLVED_STATUS = new Set(['open', 'resolved', 'manual_review']);
+const REDIRECT_STATUS = new Set(['planned']);
+const BASE_PATH_STATUS = new Set(['planned', 'verified', 'unverified', 'manual_review']);
+
+function urlPreservationDir(projectDir) {
+  return path.join(projectDir, 'state', 'url-preservation');
+}
+
+function basePathsPath(projectDir) {
+  return path.join(urlPreservationDir(projectDir), 'base-paths.json');
+}
+
+function urlLedgerPath(projectDir) {
+  return path.join(urlPreservationDir(projectDir), 'url-ledger.ndjson');
+}
+
+function redirectsPath(projectDir) {
+  return path.join(urlPreservationDir(projectDir), 'redirects.ndjson');
+}
+
+function unresolvedPath(projectDir) {
+  return path.join(urlPreservationDir(projectDir), 'unresolved.ndjson');
+}
+
+async function mkdirp(dirPath) {
+  await fs.mkdir(dirPath, { recursive: true });
+}
+
+async function pathExists(filePath) {
+  try {
+    await fs.access(filePath);
+    return true;
+  } catch (error) {
+    if (error && error.code === 'ENOENT') {
+      return false;
+    }
+    throw error;
+  }
+}
+
+async function ensureEmptyNdjson(filePath) {
+  await mkdirp(path.dirname(filePath));
+  if (!(await pathExists(filePath))) {
+    await fs.writeFile(filePath, '', 'utf8');
+    return true;
+  }
+  return false;
+}
+
+async function writeJsonAtomic(filePath, data) {
+  await mkdirp(path.dirname(filePath));
+  const tempPath = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+  await fs.writeFile(tempPath, `${JSON.stringify(data, null, 2)}\n`, 'utf8');
+  await fs.rename(tempPath, filePath);
+}
+
+async function appendNdjson(filePath, row) {
+  await mkdirp(path.dirname(filePath));
+  await fs.appendFile(filePath, `${JSON.stringify(row)}\n`, 'utf8');
+}
+
+async function readNdjson(filePath) {
+  let raw;
+  try {
+    raw = await fs.readFile(filePath, 'utf8');
+  } catch (error) {
+    if (error && error.code === 'ENOENT') {
+      return [];
+    }
+    throw error;
+  }
+  const rows = [];
+  const lines = raw.split(/\r?\n/);
+  for (let index = 0; index < lines.length; index += 1) {
+    const line = lines[index].trim();
+    if (!line) {
+      continue;
+    }
+    try {
+      rows.push(JSON.parse(line));
+    } catch (error) {
+      throw new Error(`${filePath}:${index + 1} invalid NDJSON: ${error.message}`);
+    }
+  }
+  return rows;
+}
+
+function assertObject(row, label) {
+  if (!row || typeof row !== 'object' || Array.isArray(row)) {
+    throw new Error(`${label} must be an object`);
+  }
+}
+
+function requireString(row, field, label, errors) {
+  if (!row[field] || typeof row[field] !== 'string') {
+    errors.push(`${label}.${field} must be a non-empty string`);
+  }
+}
+
+function validateTimestamp(row, field, label, errors) {
+  if (row[field] !== undefined && Number.isNaN(Date.parse(row[field]))) {
+    errors.push(`${label}.${field} must be an ISO timestamp when present`);
+  }
+}
+
+function validateUrlStatus(row, label, errors) {
+  if (row.urlStatus && !URL_STATUS.has(row.urlStatus)) {
+    errors.push(`${label}.urlStatus must be one of: ${Array.from(URL_STATUS).join(', ')}`);
+  }
+}
+
+function validateRow(row, { allowThrow = true, label = 'row', required = [], validate = null } = {}) {
+  const errors = [];
+  try {
+    assertObject(row, label);
+  } catch (error) {
+    if (allowThrow) {
+      throw error;
+    }
+    return { ok: false, errors: [error.message] };
+  }
+  if (row.schemaVersion !== SCHEMA_VERSION) {
+    errors.push(`${label}.schemaVersion must be ${SCHEMA_VERSION}`);
+  }
+  for (const field of required) {
+    requireString(row, field, label, errors);
+  }
+  validateTimestamp(row, 'createdAt', label, errors);
+  validateTimestamp(row, 'updatedAt', label, errors);
+  if (validate) {
+    validate(row, label, errors);
+  }
+  if (errors.length && allowThrow) {
+    throw new Error(errors.join('; '));
+  }
+  return { ok: errors.length === 0, errors };
+}
+
+function validateLedgerRow(row, options = {}) {
+  return validateRow(row, {
+    label: options.label || 'URL ledger row',
+    allowThrow: options.allowThrow,
+    required: [
+      'sourceSystem',
+      'sourceEntityType',
+      'sourceStableKey',
+      'targetSystem',
+      'targetEntityType',
+      'sourceRelativeUrl',
+      'urlStatus',
+    ],
+    validate: validateUrlStatus,
+  });
+}
+
+function validateRedirectRow(row, options = {}) {
+  return validateRow(row, {
+    label: options.label || 'redirect row',
+    allowThrow: options.allowThrow,
+    required: [
+      'sourceStableKey',
+      'sourceRelativeUrl',
+      'targetRelativeUrl',
+      'status',
+    ],
+    validate: (candidate, label, errors) => {
+      if (candidate.httpStatus !== 301) {
+        errors.push(`${label}.httpStatus must be 301`);
+      }
+      if (candidate.status && !REDIRECT_STATUS.has(candidate.status)) {
+        errors.push(`${label}.status must be one of: ${Array.from(REDIRECT_STATUS).join(', ')}`);
+      }
+    },
+  });
+}
+
+function validateUnresolvedRow(row, options = {}) {
+  return validateRow(row, {
+    label: options.label || 'unresolved row',
+    allowThrow: options.allowThrow,
+    required: [
+      'sourceSystem',
+      'sourceEntityType',
+      'sourceStableKey',
+      'targetSystem',
+      'targetEntityType',
+      'sourceRelativeUrl',
+      'urlStatus',
+      'status',
+    ],
+    validate: (candidate, label, errors) => {
+      validateUrlStatus(candidate, label, errors);
+      if (candidate.status && !UNRESOLVED_STATUS.has(candidate.status)) {
+        errors.push(`${label}.status must be one of: ${Array.from(UNRESOLVED_STATUS).join(', ')}`);
+      }
+    },
+  });
+}
+
+function validateBasePathEntry(row, options = {}) {
+  return validateRow(row, {
+    label: options.label || 'base path entry',
+    allowThrow: options.allowThrow,
+    required: [
+      'sourceSystem',
+      'sourceEntityType',
+      'targetSystem',
+      'targetEntityType',
+      'sourceBasePath',
+      'sourceUrlPattern',
+      'status',
+    ],
+    validate: (candidate, label, errors) => {
+      if (typeof candidate.public !== 'boolean') {
+        errors.push(`${label}.public must be a boolean`);
+      }
+      if (candidate.preserveBasePath !== undefined && typeof candidate.preserveBasePath !== 'boolean') {
+        errors.push(`${label}.preserveBasePath must be a boolean when present`);
+      }
+      if (candidate.preserveSlug !== undefined && typeof candidate.preserveSlug !== 'boolean') {
+        errors.push(`${label}.preserveSlug must be a boolean when present`);
+      }
+      if (candidate.status && !BASE_PATH_STATUS.has(candidate.status)) {
+        errors.push(`${label}.status must be one of: ${Array.from(BASE_PATH_STATUS).join(', ')}`);
+      }
+    },
+  });
+}
+
+function ledgerKey(row) {
+  return `${row.sourceStableKey}\t${row.sourceRelativeUrl}`;
+}
+
+function redirectKey(row) {
+  return `${row.sourceRelativeUrl}\t${row.targetRelativeUrl}\t${row.httpStatus}`;
+}
+
+function unresolvedKey(row) {
+  return `${row.sourceStableKey}\t${row.sourceRelativeUrl}\t${row.urlStatus}`;
+}
+
+function foldRows(rows, keyFor) {
+  const latestByKey = {};
+  for (const row of rows) {
+    latestByKey[keyFor(row)] = row;
+  }
+  return latestByKey;
+}
+
+async function appendUrlLedgerRow(projectDir, row) {
+  validateLedgerRow(row);
+  await appendNdjson(urlLedgerPath(projectDir), row);
+  return row;
+}
+
+async function appendRedirectRow(projectDir, row) {
+  validateRedirectRow(row);
+  await appendNdjson(redirectsPath(projectDir), row);
+  return row;
+}
+
+async function appendUnresolvedRow(projectDir, row) {
+  validateUnresolvedRow(row);
+  await appendNdjson(unresolvedPath(projectDir), row);
+  return row;
+}
+
+async function loadUrlLedger(projectDir) {
+  const rows = await readNdjson(urlLedgerPath(projectDir));
+  for (const row of rows) {
+    validateLedgerRow(row);
+  }
+  return { rows, byKey: foldRows(rows, ledgerKey) };
+}
+
+async function loadRedirects(projectDir) {
+  const rows = await readNdjson(redirectsPath(projectDir));
+  for (const row of rows) {
+    validateRedirectRow(row);
+  }
+  return { rows, byKey: foldRows(rows, redirectKey) };
+}
+
+async function loadUnresolved(projectDir) {
+  const rows = await readNdjson(unresolvedPath(projectDir));
+  for (const row of rows) {
+    validateUnresolvedRow(row);
+  }
+  return { rows, byKey: foldRows(rows, unresolvedKey) };
+}
+
+async function writeBasePaths(projectDir, entries) {
+  if (!Array.isArray(entries)) {
+    throw new Error('base path entries must be an array');
+  }
+  for (const entry of entries) {
+    validateBasePathEntry(entry);
+  }
+  await writeJsonAtomic(basePathsPath(projectDir), {
+    schemaVersion: SCHEMA_VERSION,
+    entries,
+  });
+  return entries;
+}
+
+async function loadBasePaths(projectDir) {
+  let raw;
+  try {
+    raw = await fs.readFile(basePathsPath(projectDir), 'utf8');
+  } catch (error) {
+    if (error && error.code === 'ENOENT') {
+      return { schemaVersion: SCHEMA_VERSION, entries: [] };
+    }
+    throw error;
+  }
+  const parsed = JSON.parse(raw);
+  const entries = Array.isArray(parsed) ? parsed : parsed.entries;
+  if (!Array.isArray(entries)) {
+    throw new Error('base-paths.json entries must be an array');
+  }
+  for (const entry of entries) {
+    validateBasePathEntry(entry);
+  }
+  return { schemaVersion: parsed.schemaVersion || SCHEMA_VERSION, entries };
+}
+
+async function initUrlPreservationState(projectDir) {
+  await mkdirp(urlPreservationDir(projectDir));
+  const actions = [];
+  if (!(await pathExists(basePathsPath(projectDir)))) {
+    await writeJsonAtomic(basePathsPath(projectDir), {
+      schemaVersion: SCHEMA_VERSION,
+      entries: [],
+    });
+    actions.push({ action: 'initialized_url_base_paths', path: 'state/url-preservation/base-paths.json' });
+  }
+  for (const [filePath, action, relativePath] of [
+    [urlLedgerPath(projectDir), 'initialized_url_ledger', 'state/url-preservation/url-ledger.ndjson'],
+    [redirectsPath(projectDir), 'initialized_url_redirects', 'state/url-preservation/redirects.ndjson'],
+    [unresolvedPath(projectDir), 'initialized_url_unresolved', 'state/url-preservation/unresolved.ndjson'],
+  ]) {
+    const created = await ensureEmptyNdjson(filePath);
+    actions.push({ action: created ? action : action.replace('initialized', 'kept'), path: relativePath });
+  }
+  await loadBasePaths(projectDir);
+  await loadUrlLedger(projectDir);
+  await loadRedirects(projectDir);
+  await loadUnresolved(projectDir);
+  return actions;
+}
+
+module.exports = {
+  SCHEMA_VERSION,
+  urlPreservationDir,
+  basePathsPath,
+  urlLedgerPath,
+  redirectsPath,
+  unresolvedPath,
+  ledgerKey,
+  redirectKey,
+  unresolvedKey,
+  validateBasePathEntry,
+  validateLedgerRow,
+  validateRedirectRow,
+  validateUnresolvedRow,
+  writeBasePaths,
+  loadBasePaths,
+  appendUrlLedgerRow,
+  appendRedirectRow,
+  appendUnresolvedRow,
+  loadUrlLedger,
+  loadRedirects,
+  loadUnresolved,
+  initUrlPreservationState,
+};