@wix/agent-skills 1.33.1 → 1.34.0

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

@@ -1,7 +1,9 @@
 #!/usr/bin/env node
 'use strict';
 
+const fs = require('node:fs');
 const path = require('node:path');
+const { approvalArtifactRefs } = require('../lib/user-actions.js');
 const {
   nowIso,
   randomId,
@@ -12,11 +14,21 @@ const {
   writeJsonAtomic,
   appendEvent,
   updateDecisionObject,
+  assertGenericDecisionKey,
+  recordPluginCmsFallbackDecision,
   updateApprovalObject,
+  autoApproveOneClick,
   updateCheckpointObject,
   transitionRun,
 } = require('../lib/orchestration-state.js');
 const { createProgressLogger, parseProgressArgs } = require('../lib/progress-log.js');
+const {
+  SOURCE_MODE_DECISION_KEYS,
+  invalidSourceModeMessage,
+  isKnownSourceMode,
+  normalizeAutomationMode,
+} = require('../lib/orchestration-decisions.js');
+const { applySiteTypePair, resolveSiteTypePair } = require('../lib/destination-choice.js');
 
 let progress;
 
@@ -26,7 +38,10 @@ function usage() {
   node scripts/orchestration-state.js validate --project-dir <dir>
   node scripts/orchestration-state.js status --project-dir <dir>
   node scripts/orchestration-state.js decide --project-dir <dir> --key <decisionKey> --value <jsonOrString> [--source user|deterministic_inference|prior_artifact] [--rationale <text>]
-  node scripts/orchestration-state.js approve --project-dir <dir> --type mapping|execution --status pending|approved|rejected|provisional [--notes <text>] [--decided-by user|system]
+      (targetSiteType: --value headless|studio|harmony [--business-type store|bookings|other|unknown] [--business-type-source user|context|not_asked] [--evidence-ref <ref>])
+  node scripts/orchestration-state.js decide-cms-fallback --project-dir <dir> --capability <id> --value approved|declined --approved-by <text> [--rationale <text>] [--coverage <plugin-coverage.json>] [--plugins-root <dir>]
+  node scripts/orchestration-state.js approve --project-dir <dir> --type mapping|execution --status pending|approved|rejected|provisional [--notes <text>] [--decided-by user|system|agent]
+  node scripts/orchestration-state.js auto-approve --project-dir <dir> --type mapping|execution [--notes <text>] [--artifact-refs <jsonArray>]
   node scripts/orchestration-state.js checkpoint --project-dir <dir> --phase discovery|mapping|setup|codegen|execution --patch <json>
   node scripts/orchestration-state.js transition --project-dir <dir> --state <state> --phase <activePhase> [--status <runStatus>] [--needs-user-input true|false] [--needs-llm true|false] [--resume-from <jsonReasonRef>]
 `);
@@ -47,6 +62,17 @@ function parseArgs(argv) {
   return args;
 }
 
+// Missing checkpoints.json or a missing phase entry renders as null; the validation
+// error list printed alongside it names the problem.
+function checkpointStatusSummary(checkpoints) {
+  const summary = {};
+  for (const phase of ['discovery', 'mapping', 'setup', 'codegen', 'execution']) {
+    const item = checkpoints && typeof checkpoints === 'object' ? checkpoints[phase] : null;
+    summary[phase] = item && typeof item === 'object' ? item.status : null;
+  }
+  return summary;
+}
+
 function parseMaybeJson(value) {
   if (value == null) {
     return value;
@@ -79,7 +105,7 @@ async function saveArtifacts(projectDir, artifacts) {
 async function main() {
   const parsed = parseProgressArgs(process.argv.slice(2));
   progress = createProgressLogger({
-    script: 'skills/replatform/scripts/orchestration-state.js',
+    script: 'skills/wix-replatform/scripts/orchestration-state.js',
     ...parsed.progress,
   });
   progress.start('Orchestration state command started', { phase: 'orchestration' });
@@ -132,13 +158,7 @@ async function main() {
       activePhase: artifacts.run.activePhase,
       runStatus: artifacts.run.status,
       approvals: artifacts.approvals,
-      checkpointStatus: {
-        discovery: artifacts.checkpoints.discovery.status,
-        mapping: artifacts.checkpoints.mapping.status,
-        setup: artifacts.checkpoints.setup.status,
-        codegen: artifacts.checkpoints.codegen.status,
-        execution: artifacts.checkpoints.execution.status,
-      },
+      checkpointStatus: checkpointStatusSummary(artifacts.checkpoints),
       errors: result.errors,
     }, null, 2));
     if (result.ok) {
@@ -153,7 +173,30 @@ async function main() {
     if (!args.key || args.value == null) {
       throw new Error('decide requires --key and --value');
     }
-    updateDecisionObject(artifacts.decisions, args.key, parseMaybeJson(args.value), {
+    assertGenericDecisionKey(args.key);
+    const decisionValue = parseMaybeJson(args.value);
+    if (['automationMode', 'interactionMode', 'runMode'].includes(args.key) &&
+        normalizeAutomationMode(decisionValue) === 'one_click' && !args.source) {
+      throw new Error('explicit one-click requires --source user');
+    }
+    // Reject an unknown source mode before anything is saved or logged, so it can never
+    // reach the router or preflight and silently downgrade to public capture.
+    if (SOURCE_MODE_DECISION_KEYS.includes(args.key) && !isKnownSourceMode(decisionValue)) {
+      throw new Error(invalidSourceModeMessage(decisionValue));
+    }
+    // The site type and Harmony business type are one pair in one write.
+    if (args.key === 'targetSiteBusinessType') {
+      throw new Error('record targetSiteBusinessType with --key targetSiteType --value harmony --business-type <store|bookings|other|unknown>');
+    }
+    if (args.key === 'targetSiteType') {
+      const pair = resolveSiteTypePair({
+        siteType: decisionValue,
+        businessType: args.businessType,
+        businessTypeSource: args.businessTypeSource || (decisionValue === 'harmony' && args.businessType === undefined ? 'user' : undefined),
+        evidenceRef: args.evidenceRef || null,
+      });
+      applySiteTypePair(artifacts.decisions, pair, { rationale: args.rationale || null, timestamp: nowIso() });
+    } else updateDecisionObject(artifacts.decisions, args.key, decisionValue, {
       source: args.source || 'user',
       rationale: args.rationale || null,
       timestamp: nowIso(),
@@ -172,11 +215,38 @@ async function main() {
     return;
   }
 
+  if (command === 'decide-cms-fallback' || command === 'decideCmsFallback') {
+    const coveragePath = args.coverage
+      ? path.resolve(args.coverage)
+      : [path.join(projectDir, 'discovery', 'plugin-coverage.json'), path.join(projectDir, 'data', 'wp-discovery', 'plugin-coverage.json')]
+        .find((candidate) => fs.existsSync(candidate));
+    if (!coveragePath || !fs.existsSync(coveragePath)) {
+      throw new Error('decide-cms-fallback needs plugin-coverage.json (discovery/ or data/wp-discovery/, or --coverage)');
+    }
+    const coverage = JSON.parse(fs.readFileSync(coveragePath, 'utf8'));
+    const coverageRow = (coverage.capabilities || []).find((row) => row.capability === args.capability && row.recognized);
+    const { key, event } = recordPluginCmsFallbackDecision(artifacts, {
+      capability: args.capability,
+      value: args.value,
+      approvedBy: args.approvedBy,
+      coverageRow,
+      pluginsRoot: args.pluginsRoot ? path.resolve(args.pluginsRoot) : undefined,
+      rationale: args.rationale || null,
+      timestamp: nowIso(),
+    });
+    await saveArtifacts(projectDir, artifacts);
+    await appendEvent(projectDir, event);
+    console.log(JSON.stringify({ ok: true, decision: key, value: args.value, mappingApproval: artifacts.approvals.mapping.status }, null, 2));
+    progress.complete('CMS-fallback decision recorded', { phase: 'orchestration', step: 'decide-cms-fallback', entity: key, artifact: projectDir });
+    return;
+  }
+
   if (command === 'approve') {
     if (!args.type || !args.status) {
       throw new Error('approve requires --type and --status');
     }
     updateApprovalObject(artifacts.approvals, args.type, args.status, {
+      artifactRefs: await approvalArtifactRefs(projectDir, { approvalType: args.type, status: args.status, decidedBy: args.decidedBy || 'user' }),
       notes: args.notes || null,
       decidedBy: args.decidedBy || 'user',
       timestamp: nowIso(),
@@ -195,12 +265,78 @@ async function main() {
     return;
   }
 
+  if (command === 'auto-approve' || command === 'autoApprove') {
+    if (!args.type) {
+      throw new Error('auto-approve requires --type');
+    }
+    const artifactRefs = args.artifactRefs == null ? [] : parseMaybeJson(args.artifactRefs);
+    if (!Array.isArray(artifactRefs)) {
+      throw new Error('--artifact-refs must be a JSON array when provided');
+    }
+    // Preserve the existing no-op/refusal behavior before performing any disk binding.
+    const probe = autoApproveOneClick(JSON.parse(JSON.stringify(artifacts)), args.type, { artifactRefs });
+    if (!probe.ok) throw new Error(`auto-approve failed: ${probe.reason}`);
+    const boundRefs = probe.changed ? await approvalArtifactRefs(projectDir, { approvalType: args.type, status: 'approved', decidedBy: 'agent', artifactRefs }) : artifactRefs;
+    const result = autoApproveOneClick(artifacts, args.type, {
+      artifactRefs: boundRefs,
+      notes: args.notes || null,
+      timestamp: nowIso(),
+    });
+    if (!result.ok) {
+      throw new Error(`auto-approve failed: ${result.reason}`);
+    }
+    await saveArtifacts(projectDir, artifacts);
+    await appendEvent(projectDir, {
+      id: randomId('evt'),
+      timestamp: nowIso(),
+      phase: artifacts.run.activePhase,
+      state: artifacts.run.currentState,
+      type: 'approval.auto_approved',
+      payload: { approvalType: args.type },
+    });
+    console.log(JSON.stringify({ ok: true, approvalType: args.type, changed: result.changed }, null, 2));
+    progress.complete('Orchestration approval auto-approved', { phase: 'orchestration', step: 'auto-approve', entity: args.type, artifact: projectDir });
+    return;
+  }
+
   if (command === 'checkpoint') {
     if (!args.phase || !args.patch) {
       throw new Error('checkpoint requires --phase and --patch');
     }
     updateCheckpointObject(artifacts.checkpoints, args.phase, parseMaybeJson(args.patch), nowIso());
     await saveArtifacts(projectDir, artifacts);
+    // Advancing a phase is a fact about how far the run got, so it belongs in the run's own
+    // journal exactly as `transition`, `decide`, `approve` and `auto-approve` put theirs there.
+    // Without this line, phase progress was remembered only in checkpoints.json, and a reader
+    // replaying the journal saw a run that never left its opening state.
+    //
+    // The payload is read back off the *persisted* checkpoint, never off `--patch`: a patch that
+    // sets only `lastCompletedStep` must still report the status the checkpoint actually holds,
+    // and reporting the argument would emit `undefined` for a field the run still carries.
+    const checkpoint = artifacts.checkpoints[args.phase];
+    const payload = {
+      phase: args.phase,
+      status: checkpoint.status ?? null,
+      // A fresh checkpoint has no completed step. Emit the null rather than dropping the key:
+      // an absent key and a null step are different facts to a reader replaying the journal.
+      lastCompletedStep: checkpoint.lastCompletedStep ?? null,
+    };
+    if (args.phase === 'execution') {
+      // Execution is the only checkpoint carrying these two, and the only one where a single
+      // status cannot distinguish "setup done, import not" from "neither started".
+      payload.setupStatus = checkpoint.setupStatus ?? null;
+      payload.importStatus = checkpoint.importStatus ?? null;
+    }
+    // After saveArtifacts, matching the four sibling commands. A crash in between leaves a
+    // checkpoint with no event; that failure mode is theirs already and is not narrowed here.
+    await appendEvent(projectDir, {
+      id: randomId('evt'),
+      timestamp: nowIso(),
+      phase: artifacts.run.activePhase,
+      state: artifacts.run.currentState,
+      type: 'checkpoint.updated',
+      payload,
+    });
     console.log(JSON.stringify({ ok: true, phase: args.phase }, null, 2));
     progress.complete('Orchestration checkpoint updated', { phase: 'orchestration', step: 'checkpoint', entity: args.phase, artifact: projectDir });
     return;

package/skills/wix-replatform/scripts/read-back-gate.js

@@ -0,0 +1,175 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('node:fs/promises');
+const path = require('node:path');
+const {
+  pathToFileURL
+} = require('node:url');
+const C = require('../lib/read-back-contract');
+const state = require('../lib/read-back-state');
+const {
+  readExtract
+} = require('../lib/read-back-extract');
+function problem(code) {
+  return Object.assign(new Error(code), {
+    code
+  });
+}
+function parse(args) {
+  const [command, directory, ...flags] = args;
+  if (!['contract', 'inventory', 'validate', 'summary'].includes(command) || !directory || directory.startsWith('--')) throw problem('usage');
+  const options = {};
+  for (let i = 0; i < flags.length; i += 2) {
+    const name = flags[i];
+    if (!['--entity', '--extract', '--builder', '--source-key', '--format'].includes(name) || !flags[i + 1] || flags[i + 1].startsWith('--') || Object.hasOwn(options, name)) throw problem('usage');
+    options[name] = flags[i + 1];
+  }
+  if (command !== 'summary' && !options['--entity']) throw problem('entity_required');
+  if (options['--entity']) C.entityKey(options['--entity']);
+  const allowed = command === 'inventory' ? ['--entity', '--extract', '--builder', '--source-key', '--format'] : ['--entity'];
+  if (Object.keys(options).some(key => !allowed.includes(key))) throw problem('usage');
+  return {
+    command,
+    projectDir: path.resolve(directory),
+    entity: options['--entity'],
+    options
+  };
+}
+async function projectFile(projectDir, supplied) {
+  const file = path.resolve(projectDir, supplied),
+    relative = path.relative(projectDir, file);
+  if (!relative || relative.startsWith(`..${path.sep}`) || relative === '..' || path.isAbsolute(relative)) throw problem('project_file_required');
+  const realProject = await fs.realpath(projectDir),
+    real = await fs.realpath(file);
+  const realRelative = path.relative(realProject, real);
+  if (!realRelative || realRelative.startsWith(`..${path.sep}`) || realRelative === '..' || path.isAbsolute(realRelative)) throw problem('project_file_required');
+  return real;
+}
+function sourceKey(dotted = 'id') {
+  const keys = dotted.split('.');
+  if (keys.some(key => !key || ['__proto__', 'prototype', 'constructor'].includes(key))) throw problem('source_key_invalid');
+  return record => {
+    let value = record;
+    for (const key of keys) value = value && Object.hasOwn(value, key) ? value[key] : undefined;
+    if (typeof value !== 'string' && !(typeof value === 'number' && Number.isFinite(value))) throw problem('source_key_missing');
+    return value;
+  };
+}
+function inventorySummary(entity, inv) {
+  return {
+    entity,
+    status: 'inventoried',
+    recordCount: inv.records.length,
+    sourcePaths: inv.sourcePaths,
+    writePaths: inv.writePaths
+  };
+}
+async function run(args) {
+  const {
+    command,
+    projectDir,
+    entity,
+    options
+  } = parse(args);
+  if (command === 'contract') {
+    const file = `mapping/entity-decisions/${entity}.json`;
+    const decision = await state.readJson(projectDir, file, {});
+    if (!decision || typeof decision !== 'object' || Array.isArray(decision)) throw problem('entity_decision_invalid');
+    await state.atomic(projectDir, file, {
+      ...decision,
+      readBackContract: C.domainContract(entity)
+    });
+    return {
+      entity,
+      status: 'contract-copied',
+      domainDigest: C.domainContract(entity).domainDigest
+    };
+  }
+  if (command === 'inventory') {
+    if (!options['--extract']) return {
+      entity,
+      status: 'not-run',
+      code: 'extract_missing',
+      exitCode: 2
+    };
+    let file;
+    try {
+      file = await projectFile(projectDir, options['--extract']);
+    } catch (error) {
+      if (error.code === 'ENOENT') return {
+        entity,
+        status: 'not-run',
+        code: 'extract_missing',
+        exitCode: 2
+      };
+      throw error;
+    }
+    if (!options['--builder']) throw problem('builder_required');
+    const builderPath = await projectFile(projectDir, options['--builder']);
+    const builderModule = await import(pathToFileURL(builderPath).href);
+    const buildWrite = builderModule.buildWrite || builderModule.default?.buildWrite;
+    if (typeof buildWrite !== 'function') throw problem('builder_export_missing');
+    const plan = await state.readJson(projectDir, 'mapping/mapping-plan.json');
+    const rows = C.mappingRows(plan, entity);
+    const inv = await C.inventory(projectDir, entity, readExtract(file, {
+      format: options['--format'] || 'auto'
+    }), {
+      sourceKey: sourceKey(options['--source-key']),
+      buildWrite,
+      rows
+    });
+    return {
+      ...inventorySummary(entity, inv),
+      preparationMs: inv.preparationMs
+    };
+  }
+  if (command === 'validate') {
+    let result;
+    try {
+      result = await C.validate(projectDir, entity);
+    } catch {
+      return {
+        entity,
+        status: 'invalid',
+        errors: ['Read-back validation could not read required artifacts or gate history.'],
+        exitCode: 2
+      };
+    }
+    return {
+      entity,
+      status: result.valid ? 'valid' : 'invalid',
+      errors: result.errors,
+      exitCode: result.valid ? 0 : 2
+    };
+  }
+  return require('../lib/read-back-summary').projectReadBackSummary(await state.load(projectDir), { entity });
+}
+async function main(args = process.argv.slice(2)) {
+  try {
+    const {
+      exitCode = 0,
+      ...result
+    } = await run(args);
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+    process.exitCode = exitCode;
+    return result;
+  } catch (error) {
+    // A generated builder or JSON parser may include source values in its message.
+    const known = new Set(['usage', 'entity_required', 'project_file_required', 'entity_decision_invalid', 'source_key_invalid', 'source_key_missing', 'builder_required', 'builder_export_missing', 'extract_record_too_large', 'extract_record_invalid', 'extract_json_invalid', 'extract_json_trailing_data', 'extract_json_array_required', 'extract_json_incomplete', 'extract_options_invalid']);
+    const result = {
+      status: 'failed',
+      code: known.has(error.code) ? error.code : 'read_back_command_failed'
+    };
+    process.stdout.write(`${JSON.stringify(result)}\n`);
+    process.exitCode = 2;
+    return result;
+  }
+}
+if (require.main === module) main();
+module.exports = {
+  main,
+  run,
+  parse,
+  sourceKey
+};

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

@@ -0,0 +1,146 @@
+#!/usr/bin/env node
+'use strict';
+
+// Local-only browser control surface. The CLI remains the migration authority; this process
+// translates a deliberately small HTTP API into argument-array CLI invocations.
+const http = require('node:http');
+const fs = require('node:fs/promises');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const { spawn } = require('node:child_process');
+
+const ROOT = path.resolve(process.env.REPLATFORM_MIGRATIONS_DIR || path.join(process.cwd(), 'migrations'));
+const CLI = path.join(__dirname, 'replatform.js');
+const PUBLIC = path.join(__dirname, '..', 'console');
+const token = crypto.randomBytes(32).toString('base64url');
+const clients = new Map();
+const active = new Map();
+const MAX_BODY = 52 * 1024 * 1024;
+const safeProject = (value) => typeof value === 'string' && /^[A-Za-z0-9][A-Za-z0-9_-]{0,99}$/.test(value);
+const projectPath = (project) => { if (!safeProject(project)) throw new Error('invalid project name'); return path.join(ROOT, project); };
+const cursorPath = (project) => path.join(projectPath(project), 'state', 'runner', 'console-cursor.json');
+
+function parseArgs() {
+  const args = process.argv.slice(2); let port = 4310;
+  for (let i = 0; i < args.length; i += 1) {
+    if (args[i] === '--port') port = Number(args[++i]);
+    else if (args[i] === '--host' && args[++i] !== '127.0.0.1') throw new Error('the console only binds to 127.0.0.1');
+    else if (args[i] !== '--host') throw new Error(`unknown option: ${args[i]}`);
+  }
+  if (!Number.isInteger(port) || port < 1 || port > 65535) throw new Error('port must be 1–65535');
+  return port;
+}
+function send(res, status, body) { res.writeHead(status, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' }); res.end(JSON.stringify(body)); }
+function originOK(req) { const origin = req.headers.origin; return !origin || origin === `http://127.0.0.1:${server.address().port}`; }
+function authorized(req, url, mutation = false) { return url.searchParams.get('token') === token && (!mutation || originOK(req)); }
+async function body(req) {
+  const chunks = []; let size = 0;
+  for await (const chunk of req) { size += chunk.length; if (size > MAX_BODY) throw new Error('request body is too large'); chunks.push(chunk); }
+  try { return JSON.parse(Buffer.concat(chunks).toString('utf8') || '{}'); } catch { throw new Error('request body must be JSON'); }
+}
+function invoke(args, { onLine } = {}) {
+  return new Promise((resolve) => {
+    const child = spawn(process.execPath, [CLI, ...args], { cwd: process.cwd(), env: process.env, stdio: ['ignore', 'pipe', 'pipe'] });
+    let stdout = ''; let stderr = ''; let partial = '';
+    child.stdout.on('data', (chunk) => { stdout += chunk; partial += chunk; const lines = partial.split('\n'); partial = lines.pop(); for (const line of lines) if (line) onLine?.(line); });
+    child.stderr.on('data', (chunk) => { stderr += chunk; });
+    child.once('close', (code, signal) => resolve({ child, code, signal, stdout, stderr }));
+  });
+}
+async function json(args) {
+  const result = await invoke(args); const line = result.stdout.trim().split('\n').filter(Boolean).at(-1);
+  let value = null; try { value = line ? JSON.parse(line) : null; } catch { /* protocol failure is returned below */ }
+  if (result.code !== 0) throw new Error(value?.message || result.stderr.trim() || `CLI failed (${result.code})`);
+  if (!value) throw new Error('CLI returned no JSON result'); return value;
+}
+function broadcast(project, event) {
+  if (event.eventId) fs.mkdir(path.dirname(cursorPath(project)), { recursive: true }).then(() => fs.writeFile(cursorPath(project), `${JSON.stringify({ schemaVersion: 1, eventId: event.eventId, timestamp: event.timestamp || new Date().toISOString() })}\n`, 'utf8')).catch(() => {});
+  for (const res of clients.get(project) || []) res.write(`id: ${event.eventId || ''}\nevent: migration\ndata: ${JSON.stringify(event)}\n\n`);
+}
+function launch(project, args) {
+  if (active.has(project)) throw new Error('this project already has a console-owned run');
+  const child = spawn(process.execPath, [CLI, ...args], { cwd: process.cwd(), env: process.env, stdio: ['ignore', 'pipe', 'pipe'] });
+  active.set(project, child); let partial = ''; let stderr = ''; let sawResult = false;
+  child.stdout.on('data', (chunk) => { partial += chunk; const lines = partial.split('\n'); partial = lines.pop(); for (const line of lines) {
+    try { const event = JSON.parse(line); if (event.type === 'result') sawResult = true; broadcast(project, event); } catch { broadcast(project, { type: 'protocol_error', message: 'The CLI emitted invalid JSONL.' }); }
+  }});
+  child.stderr.on('data', (chunk) => { stderr += chunk; });
+  child.once('close', (code) => {
+    active.delete(project);
+    if (partial) try { const event = JSON.parse(partial); if (event.type === 'result') sawResult = true; broadcast(project, event); } catch {}
+    if (!sawResult) broadcast(project, { schemaVersion: 1, eventId: `evt_console_${crypto.randomUUID()}`, timestamp: new Date().toISOString(), type: 'result', state: 'failed', message: stderr.trim() || `CLI exited with ${code}`, result: { schemaVersion: 1, runId: null, outcome: 'failed', nextAction: 'Inspect the console diagnostics and correct the reported input or local prerequisite.' } });
+  });
+  return child;
+}
+function runArgs(project, options, resume = false) {
+  const args = [resume ? 'resume' : 'run', projectPath(project), '--format', 'jsonl'];
+  if (resume) return args;
+  const pick = [['sourceUrl', '--source-url'], ['sourceMode', '--source-mode'], ['deliveryMode', '--delivery-mode'], ['destination', '--destination'], ['managementImportMode', '--management-import-mode'], ['agent', '--agent'], ['wallTimeout', '--wall-timeout'], ['idleTimeout', '--idle-timeout'], ['statusInterval', '--status-interval']];
+  for (const [key, flag] of pick) if (options[key] !== undefined && options[key] !== '') args.push(flag, String(options[key]));
+  for (const name of options.files || []) { if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,200}$/.test(name)) throw new Error('invalid uploaded file name'); args.push('--file', path.join(projectPath(project), 'intake', name)); }
+  if (options.oneClick) args.push('--one-click'); if (options.dryRun) args.push('--dry-run'); return args;
+}
+function scrubStatus(value) { if (value?.eventStream) delete value.eventStream.path; return value; }
+function setupCredentialInstructions(project, request) {
+  if (request?.kind !== 'manual_action' || request.stage !== 'setup_provisioning' || request.response?.mode !== 'none') return null;
+  return {
+    command: `cd ${projectPath(project)}\nbash ./scripts/mint-token.sh`,
+    confirmation: 'Wait for the success message confirming that WIX_AUTH_TOKEN was written. The token itself must not be displayed.',
+  };
+}
+async function replay(project, cursor, res) {
+  const args = ['tail', projectPath(project), '--format', 'jsonl']; if (cursor) args.push('--since', cursor);
+  const result = await invoke(args); for (const line of result.stdout.trim().split('\n').filter(Boolean)) { try { const event = JSON.parse(line); res.write(`id: ${event.eventId || ''}\nevent: migration\ndata: ${JSON.stringify(event)}\n\n`); } catch {} }
+}
+async function staticFile(res, name) {
+  const map = { '/': 'index.html', '/app.js': 'app.js', '/app.css': 'app.css', '/json.css': 'json.css', '/account.css': 'account.css' }; const file = map[name];
+  if (!file) return false; const content = await fs.readFile(path.join(PUBLIC, file));
+  res.writeHead(200, { 'content-type': file.endsWith('.js') ? 'text/javascript; charset=utf-8' : file.endsWith('.css') ? 'text/css; charset=utf-8' : 'text/html; charset=utf-8', 'cache-control': 'no-store' }); res.end(content); return true;
+}
+const server = http.createServer(async (req, res) => {
+  const url = new URL(req.url, `http://${req.headers.host}`); const mutation = ['POST', 'PUT', 'DELETE'].includes(req.method);
+  try {
+    // Static assets contain no state or secret. The shell itself remains token-gated.
+    if (req.method === 'GET' && (url.pathname === '/app.js' || url.pathname === '/app.css' || url.pathname === '/json.css' || url.pathname === '/account.css')) return staticFile(res, url.pathname);
+    if (!authorized(req, url, mutation)) return send(res, 403, { error: 'Local console token or origin was rejected.' });
+    if (req.method === 'GET' && !url.pathname.startsWith('/api/')) { if (await staticFile(res, url.pathname)) return; return send(res, 404, { error: 'Not found' }); }
+    if (req.method === 'GET' && url.pathname === '/api/projects') return send(res, 200, await json(['projects', '--format', 'json']));
+    // This transient, token-gated response must never enter migration artifacts or event logs.
+    if (req.method === 'GET' && url.pathname === '/api/account') return send(res, 200, await json(['account', '--format', 'json']));
+    const project = url.searchParams.get('project');
+    if (req.method === 'GET' && url.pathname === '/api/status') return send(res, 200, scrubStatus(await json(['status', projectPath(project), '--format', 'json'])));
+    if (req.method === 'GET' && url.pathname === '/api/tasks') return send(res, 200, await json(['tasks', projectPath(project), '--format', 'json']));
+    if (req.method === 'GET' && url.pathname === '/api/doctor') return send(res, 200, await json(['doctor', '--agent', url.searchParams.get('agent') || 'auto', '--format', 'json']));
+    if (req.method === 'GET' && url.pathname === '/api/requests') return send(res, 200, await json(['requests', projectPath(project), '--format', 'json']));
+    if (req.method === 'GET' && url.pathname === '/api/show') {
+      const item = url.searchParams.get('item'); const cursor = url.searchParams.get('cursor') || '0';
+      const value = await json(['show', projectPath(project), item, '--cursor', cursor, '--max-bytes', '262144', '--format', 'json']);
+      const instructions = /^uar_[0-9a-f-]+$/.test(item || '') ? setupCredentialInstructions(project, value) : null;
+      return send(res, 200, instructions ? { ...value, operatorInstructions: instructions } : value);
+    }
+    if (req.method === 'GET' && url.pathname === '/api/events') {
+      projectPath(project); res.writeHead(200, { 'content-type': 'text/event-stream', 'cache-control': 'no-cache', connection: 'keep-alive' }); res.write('retry: 2000\n\n');
+      await replay(project, req.headers['last-event-id'] || url.searchParams.get('cursor'), res);
+      const set = clients.get(project) || new Set(); set.add(res); clients.set(project, set); req.once('close', () => { set.delete(res); if (!set.size) clients.delete(project); }); return;
+    }
+    const data = await body(req);
+    if (req.method === 'POST' && url.pathname === '/api/upload') {
+      const dir = path.join(projectPath(data.project), 'intake'); const name = path.basename(String(data.name || ''));
+      if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,200}$/.test(name) || !/^[A-Za-z0-9+/=]*$/.test(data.contentBase64 || '')) throw new Error('invalid upload');
+      const content = Buffer.from(data.contentBase64, 'base64'); if (!content.length || content.length > 50 * 1024 * 1024) throw new Error('upload must be between 1 byte and 50 MB');
+      await fs.mkdir(dir, { recursive: true }); await fs.writeFile(path.join(dir, name), content, { flag: 'wx' }); return send(res, 201, { name });
+    }
+    if (req.method === 'POST' && url.pathname === '/api/run') { const projectName = data.project; launch(projectName, runArgs(projectName, data.options || {}, data.resume === true)); return send(res, 202, { project: projectName, outcome: 'starting' }); }
+    if (req.method === 'POST' && url.pathname === '/api/answer') {
+      projectPath(data.project); const args = ['answer', '--project', projectPath(data.project), '--request-id', String(data.requestId), '--format', 'json'];
+      if (data.choice !== undefined) args.push('--choice', String(data.choice)); else if (data.text !== undefined) args.push('--text', String(data.text)); else if (data.acknowledged === true) args.push('--acknowledge'); else throw new Error('an answer is required');
+      if (data.note !== undefined && data.choice === undefined && data.acknowledged !== true) throw new Error('a note requires a choice or acknowledgement');
+      if (data.note !== undefined) args.push('--note', String(data.note));
+      if (data.continue) { const streamArgs = args.filter((item, index) => !(item === '--format' || (index && args[index - 1] === '--format'))); streamArgs.push('--format', 'jsonl', '--continue'); launch(data.project, streamArgs); return send(res, 202, { project: data.project, outcome: 'resuming' }); }
+      return send(res, 200, await json(args));
+    }
+    if (req.method === 'POST' && url.pathname === '/api/cancel') return send(res, 200, await json(['cancel', projectPath(data.project), '--reason', String(data.reason || 'canceled by operator'), '--format', 'json']));
+    return send(res, 404, { error: 'Not found' });
+  } catch (error) { return send(res, 400, { error: error.message || String(error) }); }
+});
+server.listen(parseArgs(), '127.0.0.1', () => console.log(`RePlatform console: http://127.0.0.1:${server.address().port}/?token=${token}`));