@wix/agent-skills 1.33.1 → 1.35.0

package/skills/wix-replatform/lib/source-secrets.js

@@ -0,0 +1,277 @@
+'use strict';
+
+const path = require('node:path');
+const {
+  PLACEHOLDER_VALUE,
+  readEnvFile,
+  statEnvKeys,
+  statEnvValues,
+  upsertEnvFile,
+} = require('./config-env.js');
+const { buildWixDashboardUrl } = require('./wix-dashboard-url.js');
+
+const SECRET_NAME_RE = /^[A-Za-z0-9_+=@#$-]+$/;
+const DEFAULT_BASE_URL = 'https://www.wixapis.com';
+const API_PATH = '/_api/cloud-secrets-vault-server/api/v1/secrets';
+
+function authHeaderValue(token) {
+  const trimmed = String(token || '').trim();
+  if (!trimmed) {
+    throw new Error('Wix auth token is required');
+  }
+  if (/^Bearer\s+/i.test(trimmed)) return trimmed;
+  if (/^IST\./.test(trimmed)) return trimmed;
+  return `Bearer ${trimmed}`;
+}
+
+function assertSecretName(name) {
+  if (!name || typeof name !== 'string') {
+    throw new Error('secret name is required');
+  }
+  if (name.length > 50) {
+    throw new Error(`secret name "${name}" exceeds Wix's 50 character limit`);
+  }
+  if (!SECRET_NAME_RE.test(name)) {
+    throw new Error(`secret name "${name}" contains unsupported characters`);
+  }
+}
+
+function normalizeKeySpec(spec) {
+  if (typeof spec === 'string') {
+    assertSecretName(spec);
+    return { key: spec, secretName: spec };
+  }
+  if (!spec || typeof spec !== 'object' || !spec.key) {
+    throw new Error('key specs must be strings or objects with a key');
+  }
+  const key = String(spec.key);
+  const secretName = String(spec.secretName || spec.key);
+  assertSecretName(secretName);
+  return { key, secretName };
+}
+
+function isUsableSecretValue(value, placeholder = PLACEHOLDER_VALUE) {
+  return value != null && String(value).trim() !== '' && String(value) !== placeholder;
+}
+
+function safeJsonError(error) {
+  if (!error) return 'request failed';
+  return error.message || String(error);
+}
+
+function createWixSecretsClient(options = {}) {
+  const fetchImpl = options.fetchImpl || globalThis.fetch;
+  if (typeof fetchImpl !== 'function') {
+    throw new Error('fetch is unavailable; run on Node 18+ or provide fetchImpl');
+  }
+  const baseUrl = (options.baseUrl || DEFAULT_BASE_URL).replace(/\/+$/, '');
+  const authorization = authHeaderValue(options.authToken);
+  const siteId = options.siteId || null;
+
+  function headers(extra = {}) {
+    return {
+      Authorization: authorization,
+      'Content-Type': 'application/json',
+      ...(siteId ? { 'wix-site-id': siteId } : {}),
+      ...extra,
+    };
+  }
+
+  async function request(method, requestPath, body) {
+    const response = await fetchImpl(`${baseUrl}${requestPath}`, {
+      method,
+      headers: headers(),
+      body: body == null ? undefined : JSON.stringify(body),
+    });
+    const text = await response.text();
+    let json = null;
+    if (text) {
+      try {
+        json = JSON.parse(text);
+      } catch {
+        json = null;
+      }
+    }
+    if (!response.ok) {
+      const error = new Error(`Wix Secrets API ${method} ${requestPath} failed with ${response.status}`);
+      error.status = response.status;
+      error.body = json;
+      throw error;
+    }
+    return json || {};
+  }
+
+  return {
+    async listSecretInfo() {
+      const json = await request('GET', API_PATH);
+      return Array.isArray(json.secrets) ? json.secrets : [];
+    },
+    async getSecretValue(name) {
+      assertSecretName(name);
+      try {
+        const json = await request('GET', `${API_PATH}/name/${encodeURIComponent(name)}`);
+        return { exists: true, value: json.value };
+      } catch (error) {
+        if (error && error.status === 404) {
+          return { exists: false };
+        }
+        throw error;
+      }
+    },
+    async createSecret({ name, value, description }) {
+      assertSecretName(name);
+      const json = await request('POST', API_PATH, {
+        secret: {
+          name,
+          value,
+          ...(description ? { description: String(description).slice(0, 200) } : {}),
+        },
+      });
+      return { id: json.id || null };
+    },
+  };
+}
+
+async function resolveSourceSecrets(options) {
+  const envFilePath = options.envFilePath ? path.resolve(options.envFilePath) : null;
+  if (!envFilePath) {
+    throw new Error('envFilePath is required');
+  }
+  const keySpecs = (options.keys || []).map(normalizeKeySpec);
+  if (keySpecs.length === 0) {
+    throw new Error('at least one key is required');
+  }
+  const placeholder = options.placeholder || PLACEHOLDER_VALUE;
+  const createPlaceholders = options.createPlaceholders !== false;
+  const hydrate = options.hydrate !== false;
+  const project = options.project || 'migration';
+  const client = options.client;
+  if (!client) {
+    throw new Error('client is required');
+  }
+
+  let envValues = {};
+  try {
+    envValues = await readEnvFile(envFilePath);
+  } catch (error) {
+    if (!error || error.code !== 'ENOENT') {
+      throw error;
+    }
+  }
+
+  const envStatuses = statEnvValues(envValues, keySpecs.map((spec) => spec.key), { placeholder });
+  const updates = {};
+  const result = {
+    ok: true,
+    placeholder,
+    dashboardUrl: options.metaSiteId
+      ? buildWixDashboardUrl(options.metaSiteId, { path: 'developer-tools/secrets-manager' })
+      : null,
+    keys: {},
+    unresolvedKeys: [],
+    hydratedKeys: [],
+    localPresentKeys: [],
+  };
+
+  for (const spec of keySpecs) {
+    const localStatus = envStatuses[spec.key];
+    const item = {
+      key: spec.key,
+      secretName: spec.secretName,
+      localStatus,
+      status: localStatus === 'present' ? 'local_present' : 'missing',
+    };
+
+    if (localStatus === 'present') {
+      result.localPresentKeys.push(spec.key);
+      result.keys[spec.key] = item;
+      continue;
+    }
+
+    let secretRead;
+    try {
+      secretRead = await client.getSecretValue(spec.secretName);
+    } catch (error) {
+      item.status = 'unreadable';
+      item.error = safeJsonError(error);
+      result.unresolvedKeys.push(spec.key);
+      result.ok = false;
+      result.keys[spec.key] = item;
+      continue;
+    }
+
+    if (secretRead.exists && isUsableSecretValue(secretRead.value, placeholder)) {
+      if (hydrate) {
+        updates[spec.key] = secretRead.value;
+        result.hydratedKeys.push(spec.key);
+        item.status = 'hydrated';
+      } else {
+        item.status = 'secret_present';
+      }
+      result.keys[spec.key] = item;
+      continue;
+    }
+
+    if (secretRead.exists) {
+      item.status = 'placeholder';
+      result.unresolvedKeys.push(spec.key);
+      result.keys[spec.key] = item;
+      continue;
+    }
+
+    if (!createPlaceholders) {
+      item.status = 'missing';
+      result.unresolvedKeys.push(spec.key);
+      result.keys[spec.key] = item;
+      continue;
+    }
+
+    try {
+      await client.createSecret({
+        name: spec.secretName,
+        value: placeholder,
+        description: `RePlatform source credential for ${project}: ${spec.key}`,
+      });
+      item.status = 'created';
+      result.unresolvedKeys.push(spec.key);
+    } catch (error) {
+      item.status = 'failed';
+      item.error = safeJsonError(error);
+      result.unresolvedKeys.push(spec.key);
+      result.ok = false;
+    }
+    result.keys[spec.key] = item;
+  }
+
+  if (Object.keys(updates).length > 0) {
+    await upsertEnvFile(envFilePath, updates);
+  }
+
+  // Presence-only report of the local env file after this call (never values). This is the
+  // sanctioned way to confirm hydration; vault outcomes stay in result.keys[key].status.
+  result.postHydrationReport = await statEnvKeys(
+    envFilePath,
+    keySpecs.map((spec) => spec.key),
+    { placeholder },
+  );
+
+  result.needsUser = result.unresolvedKeys.length > 0;
+  if (result.needsUser) {
+    result.instruction = [
+      result.dashboardUrl ? `Open ${result.dashboardUrl}` : 'Open the site dashboard Secrets Manager.',
+      `Keys: ${result.unresolvedKeys.join(', ')}`,
+      'For each key click the 3 dots --> edit --> Retrieve value --> set the real value --> click Change secret',
+    ].join('\n');
+  }
+
+  return result;
+}
+
+module.exports = {
+  PLACEHOLDER_VALUE,
+  authHeaderValue,
+  createWixSecretsClient,
+  isUsableSecretValue,
+  normalizeKeySpec,
+  resolveSourceSecrets,
+};

package/skills/wix-replatform/lib/structured-link-patch.js

@@ -0,0 +1,59 @@
+'use strict';
+
+const { decodeHtmlEntities } = require('./link-census.js');
+
+function escapeAttribute(value, quote) {
+  return value.replace(/&/g, '&').replace(quote === '"' ? /"/g : /'/g, quote === '"' ? '"' : ''');
+}
+
+function patchHtmlHref(html, occurrence, destination) {
+  if (typeof html !== 'string' || !/^char:\d+$/.test(occurrence.location || '')) throw new Error('HTML link location required');
+  const start = Number(occurrence.location.slice(5));
+  const fragment = html.slice(start);
+  const match = /^(href|action)\s*=\s*(["'])(.*?)\2/is.exec(fragment);
+  if (!match || decodeHtmlEntities(match[3]) !== occurrence.original) throw new Error('HTML link location or original value changed');
+  const replacement = `${match[1]}=${match[2]}${escapeAttribute(destination, match[2])}${match[2]}`;
+  return { value: `${html.slice(0, start)}${replacement}${html.slice(start + match[0].length)}`, preservedUnrelated: true, changedLocations: [occurrence.location] };
+}
+
+function jsonPathParts(location) {
+  if (!location || !location.startsWith('$.')) throw new Error('JSON field location required');
+  const parts = [];
+  for (const match of location.slice(2).matchAll(/(?:^|\.)([^.\[\]]+)|\[(\d+)\]/g)) parts.push(match[1] === undefined ? Number(match[2]) : match[1]);
+  if (!parts.length) throw new Error('unsupported JSON field location');
+  return parts;
+}
+
+function patchJsonLink(value, occurrence, destination) {
+  const clone = structuredClone(value);
+  const parts = jsonPathParts(occurrence.location);
+  let parent = clone;
+  for (const part of parts.slice(0, -1)) {
+    parent = parent && parent[part];
+    if (parent === undefined) throw new Error('JSON link location missing');
+  }
+  const key = parts.at(-1);
+  if (!parent || parent[key] !== occurrence.original) throw new Error('JSON link original value changed');
+  parent[key] = destination;
+  return { value: clone, preservedUnrelated: true, changedLocations: [occurrence.location] };
+}
+
+function structuredLinkPatch(baseValue, occurrence, destination) {
+  if (occurrence.location && occurrence.location.startsWith('char:')) return patchHtmlHref(baseValue, occurrence, destination);
+  const embedded = /^(\$\..+):(char:\d+)$/.exec(occurrence.location || '');
+  if (embedded) {
+    if (typeof baseValue === 'string') return patchHtmlHref(baseValue, { ...occurrence, location: embedded[2] }, destination);
+    const clone = structuredClone(baseValue);
+    const parts = jsonPathParts(embedded[1]);
+    let parent = clone;
+    for (const part of parts.slice(0, -1)) parent = parent && parent[part];
+    if (!parent || typeof parent[parts.at(-1)] !== 'string') throw new Error('embedded HTML field missing');
+    const patched = patchHtmlHref(parent[parts.at(-1)], { ...occurrence, location: embedded[2] }, destination);
+    parent[parts.at(-1)] = patched.value;
+    return { value: clone, preservedUnrelated: true, changedLocations: [occurrence.location] };
+  }
+  if (occurrence.location && occurrence.location.startsWith('$.')) return patchJsonLink(baseValue, occurrence, destination);
+  throw new Error('unsupported link patch location');
+}
+
+module.exports = { patchHtmlHref, patchJsonLink, structuredLinkPatch };

package/skills/wix-replatform/lib/task-state.js

@@ -0,0 +1,110 @@
+'use strict';
+
+// Durable, deliberately small operator-facing work state. It is not a transcript and it
+// never derives tasks from vendor output. The supervisor is the only normal writer.
+const fs = require('node:fs/promises');
+const path = require('node:path');
+const { writeJsonAtomic } = require('./orchestration-state.js');
+
+const SCHEMA_VERSION = 1;
+const taskStatePath = (projectDir) => path.join(projectDir, 'state', 'runner', 'task-state.json');
+const now = () => new Date().toISOString();
+const terminal = new Set(['completed', 'blocked', 'failed', 'canceled', 'interrupted']);
+const taskStates = new Set(['planned', 'running', 'waiting_for_input', ...terminal]);
+const agentStates = new Set(['running', ...terminal]);
+
+async function readTaskState(projectDir) {
+  try {
+    const value = JSON.parse(await fs.readFile(taskStatePath(projectDir), 'utf8'));
+    if (value?.schemaVersion !== SCHEMA_VERSION || !Array.isArray(value.tasks) || !Array.isArray(value.agents)) return null;
+    return value;
+  } catch (error) {
+    if (error.code === 'ENOENT') return null;
+    throw error;
+  }
+}
+
+async function writeTaskState(projectDir, state) {
+  const next = { ...state, schemaVersion: SCHEMA_VERSION, updatedAt: now() };
+  await fs.mkdir(path.dirname(taskStatePath(projectDir)), { recursive: true });
+  await writeJsonAtomic(taskStatePath(projectDir), next);
+  return next;
+}
+
+function createTaskState(runId) { return { schemaVersion: SCHEMA_VERSION, runId, updatedAt: now(), tasks: [], agents: [] }; }
+function routeTitle(route) { return route.nextResource ? `Run ${route.nextResource}` : `Resolve ${String(route.nextState || 'migration').replaceAll('_', ' ')}`; }
+function routeValue(route) { return { state: route.nextState || 'unknown', reason: route.reason || 'unknown', resource: route.nextResource || null }; }
+function currentTask(state) { return state.tasks.find((task) => ['running', 'waiting_for_input', 'planned'].includes(task.state)) || null; }
+
+function finishTask(state, task, outcome, endedAt = now()) {
+  if (!task || !taskStates.has(outcome) || terminal.has(task.state)) return;
+  task.state = outcome; task.endedAt = endedAt;
+  for (const agent of state.agents.filter((item) => item.taskId === task.taskId && item.state === 'running')) {
+    agent.state = outcome === 'completed' ? 'completed' : outcome;
+    agent.endedAt = endedAt;
+  }
+}
+
+function selectRoute(state, route) {
+  const value = routeValue(route); const active = currentTask(state);
+  if (active && active.kind === 'route' && active.route.state === value.state && active.route.reason === value.reason && active.route.resource === value.resource) return active;
+  if (active) finishTask(state, active, 'completed');
+  const task = { taskId: `route:${state.tasks.filter((item) => item.kind === 'route').length + 1}`, parentTaskId: null, title: routeTitle(route), kind: 'route', state: 'planned', route: value, createdAt: now(), startedAt: null, endedAt: null };
+  state.tasks.push(task); return task;
+}
+
+function startRoute(state, route) {
+  const task = selectRoute(state, route);
+  task.state = 'running'; task.startedAt ||= now();
+  return task;
+}
+
+function waitForInput(state, request) {
+  let task = currentTask(state);
+  if (!task) {
+    task = { taskId: `route:${state.tasks.filter((item) => item.kind === 'route').length + 1}`, parentTaskId: null, title: request?.title || 'Await user action', kind: 'route', state: 'waiting_for_input', route: { state: 'awaiting_user_action', reason: 'pending_user_action', resource: null }, createdAt: now(), startedAt: null, endedAt: null };
+    state.tasks.push(task);
+  }
+  task.state = 'waiting_for_input';
+  return task;
+}
+
+function startDirectAgent(state, task, adapter, pid) {
+  const agentId = `agent:${adapter}:${pid || adapter}`;
+  let agent = state.agents.find((item) => item.agentId === agentId);
+  if (!agent) {
+    agent = { agentId, taskId: task.taskId, parentAgentId: null, adapter, label: `${adapter} agent`, state: 'running', pid: Number.isInteger(pid) ? pid : null, startedAt: now(), endedAt: null };
+    state.agents.push(agent);
+  } else { agent.state = 'running'; agent.endedAt = null; }
+  return agent;
+}
+
+function finishDirectAgent(state, agentId, outcome) {
+  const agent = state.agents.find((item) => item.agentId === agentId);
+  if (agent && agent.state === 'running') { agent.state = outcome; agent.endedAt = now(); }
+}
+
+function recordWorker(state, taskId, adapter, report) {
+  if (!report || typeof report !== 'object' || !/^[A-Za-z0-9._:-]{1,160}$/.test(report.workerId || '') || !agentStates.has(report.state) || typeof report.label !== 'string' || !report.label.trim()) return false;
+  const parentAgentId = report.parentWorkerId ? `agent:${adapter}:worker:${report.parentWorkerId}` : null;
+  if (parentAgentId && !state.agents.some((item) => item.agentId === parentAgentId)) return false;
+  const agentId = `agent:${adapter}:worker:${report.workerId}`;
+  let agent = state.agents.find((item) => item.agentId === agentId);
+  if (!agent) { agent = { agentId, taskId, parentAgentId, adapter, label: report.label.trim(), state: report.state, pid: null, startedAt: report.startedAt || now(), endedAt: terminal.has(report.state) ? (report.endedAt || now()) : null }; state.agents.push(agent); }
+  else { agent.label = report.label.trim(); agent.state = report.state; agent.endedAt = terminal.has(report.state) ? (report.endedAt || now()) : null; }
+  return true;
+}
+
+function finishCurrent(state, outcome) { finishTask(state, currentTask(state), outcome); }
+
+async function reconcileTaskState(projectDir, state) {
+  let changed = false;
+  for (const agent of state.agents.filter((item) => item.state === 'running' && Number.isInteger(item.pid))) {
+    try { process.kill(agent.pid, 0); } catch { agent.state = 'interrupted'; agent.endedAt = now(); changed = true; }
+  }
+  const activeTask = currentTask(state);
+  if (activeTask && state.agents.some((item) => item.taskId === activeTask.taskId && item.state === 'interrupted')) { activeTask.state = 'interrupted'; activeTask.endedAt = now(); changed = true; }
+  return changed ? writeTaskState(projectDir, state) : state;
+}
+
+module.exports = { SCHEMA_VERSION, taskStatePath, readTaskState, writeTaskState, createTaskState, selectRoute, startRoute, waitForInput, startDirectAgent, finishDirectAgent, recordWorker, finishCurrent, reconcileTaskState };