@riddledc/riddle-proof 0.5.54 → 0.5.56

package/dist/{chunk-UR6ADV4Y.js → chunk-3CVGVQTQ.js}

@@ -87,12 +87,94 @@ async function deployRiddleStaticPreview(config, directory, label) {
     raw: published
   };
 }
+function createTarball(directory, label, exclude = []) {
+  const scratch = mkdtempSync(path.join(tmpdir(), "riddle-upload-"));
+  const tarball = path.join(scratch, `${label}.tar.gz`);
+  const excludeArgs = exclude.flatMap((item) => ["--exclude", item]);
+  try {
+    execFileSync("tar", ["czf", tarball, ...excludeArgs, "-C", directory, "."], { stdio: "pipe" });
+    return { scratch, tarball };
+  } catch (error) {
+    rmSync(scratch, { recursive: true, force: true });
+    throw error;
+  }
+}
 function parseRiddleViewport(value) {
   if (!value) return void 0;
   const match = /^(\d+)x(\d+)$/.exec(value.trim());
   if (!match) throw new Error("viewport must look like 1280x720");
   return { width: Number(match[1]), height: Number(match[2]) };
 }
+function scriptErrorFrom(job) {
+  const nested = job?.proof_of_execution && typeof job.proof_of_execution === "object" && !Array.isArray(job.proof_of_execution) ? job.proof_of_execution : null;
+  return typeof job?.script_error === "string" && job.script_error.trim() ? job.script_error : typeof nested?.script_error === "string" && nested.script_error.trim() ? nested.script_error : null;
+}
+async function runRiddleServerPreview(config, input) {
+  if (!input.directory?.trim()) throw new Error("directory is required");
+  if (!input.script?.trim()) throw new Error("script is required");
+  const port = input.port || 3e3;
+  const routePath = input.path || "/";
+  const timeoutSec = input.timeoutSec || 180;
+  const created = await riddleRequestJson(config, "/v1/server-preview", {
+    method: "POST",
+    body: JSON.stringify({
+      image: input.image || "node:22-slim",
+      command: input.command || "node scripts/riddleSpaPreviewServer.mjs build 3000",
+      port,
+      path: routePath,
+      readiness_path: input.readinessPath || routePath,
+      readiness_timeout: input.readinessTimeoutSec || 90,
+      wait_until: input.waitUntil || "domcontentloaded",
+      wait_for_selector: input.waitForSelector || "body",
+      navigation_timeout: input.navigationTimeoutSec || 60,
+      viewport: input.viewport,
+      timeout: timeoutSec,
+      script: input.script
+    })
+  });
+  const jobId = String(created.job_id || "");
+  const uploadUrl = String(created.upload_url || "");
+  if (!jobId || !uploadUrl) {
+    throw new Error(`Riddle server preview create response was missing job_id or upload_url.`);
+  }
+  const { scratch, tarball } = createTarball(input.directory, jobId, [
+    ".git",
+    "node_modules",
+    "test-results",
+    ...input.exclude || []
+  ]);
+  try {
+    const upload = await fetchFor(config)(uploadUrl, {
+      method: "PUT",
+      headers: { "Content-Type": "application/gzip" },
+      body: readFileSync(tarball)
+    });
+    if (!upload.ok) throw new RiddleApiError(uploadUrl, upload.status, await upload.text());
+  } finally {
+    rmSync(scratch, { recursive: true, force: true });
+  }
+  await riddleRequestJson(config, `/v1/server-preview/${jobId}/start`, {
+    method: "POST"
+  });
+  let job = null;
+  const attempts = input.pollAttempts || Math.ceil((timeoutSec + 90) / 2);
+  const intervalMs = input.pollIntervalMs || 2e3;
+  for (let index = 0; index < attempts; index += 1) {
+    job = await riddleRequestJson(config, `/v1/server-preview/${jobId}`);
+    if (isTerminalRiddleJobStatus(job.status)) break;
+    if (index + 1 < attempts) await new Promise((resolve) => setTimeout(resolve, intervalMs));
+  }
+  const status = job?.status ? String(job.status) : null;
+  const scriptError = scriptErrorFrom(job);
+  return {
+    ok: (status === "completed" || status === "complete") && !scriptError,
+    job_id: jobId,
+    status,
+    terminal: isTerminalRiddleJobStatus(status),
+    script_error: scriptError,
+    job
+  };
+}
 async function runRiddleScript(config, input) {
   if (!input.url?.trim()) throw new Error("url is required");
   if (!input.script?.trim()) throw new Error("script is required");
@@ -144,6 +226,7 @@ function createRiddleApiClient(config = {}) {
     requestJson: (pathname, init) => riddleRequestJson(config, pathname, init),
     deployStaticPreview: (directory, label) => deployRiddleStaticPreview(config, directory, label),
     runScript: (input) => runRiddleScript(config, input),
+    runServerPreview: (input) => runRiddleServerPreview(config, input),
     pollJob: (jobId, options) => pollRiddleJob(config, jobId, options)
   };
 }
@@ -156,6 +239,7 @@ export {
   riddleRequestJson,
   deployRiddleStaticPreview,
   parseRiddleViewport,
+  runRiddleServerPreview,
   runRiddleScript,
   isTerminalRiddleJobStatus,
   pollRiddleJob,

package/dist/chunk-53DJMNQ6.js

@@ -0,0 +1,276 @@
+// src/basic-gameplay.ts
+var RIDDLE_PROOF_BASIC_GAMEPLAY_VERSION = "riddle-proof.basic-gameplay.v1";
+var RIDDLE_PROOF_BASIC_GAMEPLAY_ASSESSMENT_VERSION = "riddle-proof.basic-gameplay.assessment.v1";
+var RIDDLE_PROOF_BASIC_GAMEPLAY_CATCH_VERSION = "riddle-proof.basic-gameplay.catch.v1";
+var BASIC_GAMEPLAY_CONTAINER_KEYS = [
+  "basic_gameplay",
+  "basicGameplay",
+  "basic_gameplay_evidence",
+  "basicGameplayEvidence",
+  "gameplay_proof",
+  "gameplayProof"
+];
+function assessBasicGameplayEvidence(evidence, options = {}) {
+  const run = extractBasicGameplayEvidence(evidence);
+  if (!run) {
+    return {
+      version: RIDDLE_PROOF_BASIC_GAMEPLAY_ASSESSMENT_VERSION,
+      evidence_present: false,
+      passed: false,
+      checked_routes: 0,
+      passing_routes: 0,
+      failing_routes: [],
+      failure_counts: {},
+      warning_counts: {},
+      route_results: []
+    };
+  }
+  const routeResults = (run.results || []).map((route) => assessBasicGameplayRoute(route, options));
+  const failingRoutes = routeResults.filter((result) => !result.ok).map((result) => ({
+    name: result.name,
+    path: result.path,
+    failures: result.failures,
+    warnings: result.warnings
+  }));
+  return {
+    version: RIDDLE_PROOF_BASIC_GAMEPLAY_ASSESSMENT_VERSION,
+    evidence_present: true,
+    passed: failingRoutes.length === 0,
+    checked_routes: routeResults.length,
+    passing_routes: routeResults.filter((result) => result.ok).length,
+    failing_routes: failingRoutes,
+    failure_counts: countCodes(routeResults.flatMap((result) => result.failures)),
+    warning_counts: countCodes(routeResults.flatMap((result) => result.warnings)),
+    route_results: routeResults
+  };
+}
+function assessBasicGameplayRoute(route, options = {}) {
+  const maxMobileOverflowPx = options.maxMobileOverflowPx ?? 4;
+  const minBodyTextLength = options.minBodyTextLength ?? 20;
+  const minVisibleLargeNodes = options.minVisibleLargeNodes ?? 3;
+  const minSurfaceLargeNodes = options.minSurfaceLargeNodes ?? 8;
+  const warnOnMissingResetPath = options.warnOnMissingResetPath ?? true;
+  const warnOnConsoleError = options.warnOnConsoleError ?? true;
+  const failOnConsoleError = options.failOnConsoleError ?? false;
+  const failures = [];
+  const warnings = [];
+  const initial = route.initial || {};
+  const timed = route.timed || {};
+  const afterAction = route.after_action || route.afterAction || {};
+  const mobile = route.mobile || {};
+  const timedChange = changed(initial, timed);
+  const actionChange = changed(timed, afterAction);
+  const surfaceVisible = numberValue(initial.visible_canvas_count) > 0 || numberValue(initial.enabled_clickable_count) > 0 || numberValue(initial.visible_large_node_count) >= minSurfaceLargeNodes;
+  const actionResults = listValue(route.action_results || route.actionResults);
+  const actionAttempted = actionResults.some((result) => result.ok === true && result.action !== "wait");
+  const actionFailed = actionResults.some((result) => result.ok === false && result.action !== "wait");
+  const stateChangeObserved = actionChange.changed || timedChange.changed;
+  const resetPathPresent = numberValue(initial.reset_control_count) > 0 || numberValue(timed.reset_control_count) > 0 || numberValue(afterAction.reset_control_count) > 0;
+  const responseStatus = firstNumber(route.http_status, route.response_status, route.status);
+  const pageErrorCount = numberValue(route.page_error_count);
+  const consoleErrorCount = numberValue(route.console_error_count);
+  const mobileOverflowPx = numberValue(mobile.overflow_px);
+  if (responseStatus !== null && responseStatus >= 400) failures.push("route_http_error");
+  if (pageErrorCount > 0) failures.push("fatal_page_error");
+  if (numberValue(initial.body_text_length) < minBodyTextLength && numberValue(initial.visible_large_node_count) < minVisibleLargeNodes) {
+    failures.push("route_blank_or_thin");
+  }
+  if (!surfaceVisible) failures.push("no_game_surface");
+  if (mobileOverflowPx > maxMobileOverflowPx) failures.push("mobile_horizontal_overflow");
+  if (!actionAttempted && !timedChange.changed) failures.push("primary_control_missing");
+  if (actionAttempted && !stateChangeObserved) failures.push("primary_control_inert");
+  if (failOnConsoleError && consoleErrorCount > 0) failures.push("fatal_page_error");
+  if (numberValue(initial.visible_canvas_count) > 0 && actionAttempted && !timedChange.canvas_changed && !actionChange.canvas_changed && !actionChange.screenshot_changed) {
+    warnings.push("canvas_inert");
+  }
+  if (actionFailed) warnings.push("some_actions_failed");
+  if (warnOnMissingResetPath && !resetPathPresent && route.requires_reset !== false && actionAttempted && stateChangeObserved) {
+    warnings.push("missing_reset_path");
+  }
+  if (warnOnConsoleError && consoleErrorCount > 0) warnings.push("critical_console_error");
+  return {
+    name: route.name,
+    path: route.path,
+    ok: failures.length === 0,
+    failures,
+    warnings,
+    signals: {
+      route_loaded: !failures.includes("route_http_error") && !failures.includes("route_blank_or_thin"),
+      surface_visible: surfaceVisible,
+      action_attempted: actionAttempted,
+      timed_progression_observed: timedChange.changed,
+      first_interaction_observed: actionChange.changed,
+      state_change_observed: stateChangeObserved,
+      mobile_overflow_absent: mobileOverflowPx <= maxMobileOverflowPx,
+      reset_path_present: resetPathPresent,
+      fatal_errors_absent: pageErrorCount === 0
+    },
+    diffs: {
+      timed: timedChange,
+      after_action: actionChange
+    }
+  };
+}
+function createBasicGameplayCatchSummary(input, options = {}) {
+  const before = summarizeAssessment(assessBasicGameplayEvidence(input.before, options));
+  const after = input.after === void 0 ? void 0 : summarizeAssessment(assessBasicGameplayEvidence(input.after, options));
+  const fixed = Boolean(after && before.notable_codes.length > 0 && after.passed && after.notable_codes.length === 0);
+  const title = input.title || [
+    input.site || "Basic gameplay",
+    input.route ? `${input.route} proof catch` : "proof catch"
+  ].join(" ");
+  const beforeCodes = before.notable_codes.length ? before.notable_codes.join(", ") : "no failing or warning codes";
+  const afterCodes = after ? after.notable_codes.length ? after.notable_codes.join(", ") : "no failing or warning codes" : "not verified";
+  const summaryLines = [
+    `Before: ${before.checked_routes} checked, ${before.passing_routes} passing, codes: ${beforeCodes}.`,
+    after ? `After: ${after.checked_routes} checked, ${after.passing_routes} passing, codes: ${afterCodes}.` : "After: not provided."
+  ];
+  if (input.fix?.summary) summaryLines.push(`Fix: ${input.fix.summary}`);
+  if (input.artifacts?.length) summaryLines.push(`Artifacts: ${input.artifacts.length} attached.`);
+  return {
+    version: RIDDLE_PROOF_BASIC_GAMEPLAY_CATCH_VERSION,
+    title,
+    site: input.site,
+    route: input.route,
+    detected_at: input.detected_at || (/* @__PURE__ */ new Date()).toISOString(),
+    before,
+    after,
+    fixed,
+    fix: input.fix,
+    artifacts: input.artifacts || [],
+    summary_lines: summaryLines,
+    marketing_summary: fixed ? `${title}: Riddle Proof caught ${beforeCodes}; after the fix, ${afterCodes}.` : `${title}: Riddle Proof caught ${beforeCodes}; after evidence is ${after ? "not yet clean" : "not yet attached"}.`
+  };
+}
+function extractBasicGameplayEvidence(...sources) {
+  const seen = /* @__PURE__ */ new Set();
+  for (const source of sources) {
+    const found = findBasicGameplayEvidence(source, seen);
+    if (found) return found;
+  }
+  return null;
+}
+function summarizeAssessment(assessment) {
+  return {
+    evidence_present: assessment.evidence_present,
+    passed: assessment.passed,
+    checked_routes: assessment.checked_routes,
+    passing_routes: assessment.passing_routes,
+    failing_routes: assessment.failing_routes,
+    failure_counts: assessment.failure_counts,
+    warning_counts: assessment.warning_counts,
+    notable_codes: [
+      ...Object.keys(assessment.failure_counts),
+      ...Object.keys(assessment.warning_counts)
+    ].sort()
+  };
+}
+function findBasicGameplayEvidence(value, seen, depth = 0) {
+  if (depth > 6 || value === null || value === void 0) return null;
+  if (typeof value === "string") {
+    const parsed = parseJson(value);
+    return parsed === null ? null : findBasicGameplayEvidence(parsed, seen, depth + 1);
+  }
+  if (Array.isArray(value)) {
+    if (seen.has(value)) return null;
+    seen.add(value);
+    if (value.some((item) => hasRouteShape(recordValue(item)))) {
+      return { results: value.filter((item) => hasRouteShape(recordValue(item))) };
+    }
+    for (const item of value) {
+      const found = findBasicGameplayEvidence(item, seen, depth + 1);
+      if (found) return found;
+    }
+    return null;
+  }
+  const record = recordValue(value);
+  if (!record || seen.has(record)) return null;
+  seen.add(record);
+  if (record.version === RIDDLE_PROOF_BASIC_GAMEPLAY_VERSION || Array.isArray(record.results)) {
+    return {
+      ...record,
+      results: listValue(record.results).filter((item) => Boolean(recordValue(item)))
+    };
+  }
+  if (hasRouteShape(record)) {
+    return { results: [record] };
+  }
+  for (const key of BASIC_GAMEPLAY_CONTAINER_KEYS) {
+    if (Object.prototype.hasOwnProperty.call(record, key)) {
+      const nested = findBasicGameplayEvidence(record[key], seen, depth + 1);
+      if (nested) return nested;
+    }
+  }
+  for (const item of Object.values(record)) {
+    const found = findBasicGameplayEvidence(item, seen, depth + 1);
+    if (found) return found;
+  }
+  return null;
+}
+function hasRouteShape(record) {
+  return Boolean(record && (record.initial || record.after_action || record.afterAction || record.action_results || record.actionResults) && (record.path || record.name));
+}
+function changed(before, after) {
+  const bodyTextChanged = Boolean(before.body_text_hash && after.body_text_hash && before.body_text_hash !== after.body_text_hash);
+  const screenshotChanged = Boolean(before.screenshot_hash && after.screenshot_hash && before.screenshot_hash !== after.screenshot_hash);
+  const beforeCanvasHashes = canvasHashes(before.canvases);
+  const afterCanvasHashes = canvasHashes(after.canvases);
+  const canvasChanged = Boolean(beforeCanvasHashes && afterCanvasHashes && beforeCanvasHashes !== afterCanvasHashes);
+  return {
+    body_text_changed: bodyTextChanged,
+    screenshot_changed: screenshotChanged,
+    canvas_changed: canvasChanged,
+    changed: bodyTextChanged || screenshotChanged || canvasChanged
+  };
+}
+function canvasHashes(canvases) {
+  return (canvases || []).map((canvas) => canvas.hash).filter(Boolean).join("|");
+}
+function countCodes(codes) {
+  const counts = {};
+  for (const code of codes) counts[code] = (counts[code] || 0) + 1;
+  return counts;
+}
+function firstNumber(...values) {
+  for (const value of values) {
+    const number = numericValue(value);
+    if (number !== null) return number;
+  }
+  return null;
+}
+function numberValue(value) {
+  return numericValue(value) ?? 0;
+}
+function numericValue(value) {
+  if (typeof value === "number" && Number.isFinite(value)) return value;
+  if (typeof value === "string" && value.trim()) {
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? parsed : null;
+  }
+  return null;
+}
+function recordValue(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : null;
+}
+function listValue(value) {
+  return Array.isArray(value) ? value : [];
+}
+function parseJson(value) {
+  const trimmed = value.trim();
+  if (!trimmed || !/^[{[]/.test(trimmed)) return null;
+  try {
+    return JSON.parse(trimmed);
+  } catch {
+    return null;
+  }
+}
+
+export {
+  RIDDLE_PROOF_BASIC_GAMEPLAY_VERSION,
+  RIDDLE_PROOF_BASIC_GAMEPLAY_ASSESSMENT_VERSION,
+  RIDDLE_PROOF_BASIC_GAMEPLAY_CATCH_VERSION,
+  assessBasicGameplayEvidence,
+  assessBasicGameplayRoute,
+  createBasicGameplayCatchSummary,
+  extractBasicGameplayEvidence
+};

package/dist/cli.cjs

@@ -6487,12 +6487,94 @@ async function deployRiddleStaticPreview(config, directory, label) {
     raw: published
   };
 }
+function createTarball(directory, label, exclude = []) {
+  const scratch = (0, import_node_fs5.mkdtempSync)(import_node_path5.default.join((0, import_node_os2.tmpdir)(), "riddle-upload-"));
+  const tarball = import_node_path5.default.join(scratch, `${label}.tar.gz`);
+  const excludeArgs = exclude.flatMap((item) => ["--exclude", item]);
+  try {
+    (0, import_node_child_process4.execFileSync)("tar", ["czf", tarball, ...excludeArgs, "-C", directory, "."], { stdio: "pipe" });
+    return { scratch, tarball };
+  } catch (error) {
+    (0, import_node_fs5.rmSync)(scratch, { recursive: true, force: true });
+    throw error;
+  }
+}
 function parseRiddleViewport(value) {
   if (!value) return void 0;
   const match = /^(\d+)x(\d+)$/.exec(value.trim());
   if (!match) throw new Error("viewport must look like 1280x720");
   return { width: Number(match[1]), height: Number(match[2]) };
 }
+function scriptErrorFrom(job) {
+  const nested = job?.proof_of_execution && typeof job.proof_of_execution === "object" && !Array.isArray(job.proof_of_execution) ? job.proof_of_execution : null;
+  return typeof job?.script_error === "string" && job.script_error.trim() ? job.script_error : typeof nested?.script_error === "string" && nested.script_error.trim() ? nested.script_error : null;
+}
+async function runRiddleServerPreview(config, input) {
+  if (!input.directory?.trim()) throw new Error("directory is required");
+  if (!input.script?.trim()) throw new Error("script is required");
+  const port = input.port || 3e3;
+  const routePath = input.path || "/";
+  const timeoutSec = input.timeoutSec || 180;
+  const created = await riddleRequestJson(config, "/v1/server-preview", {
+    method: "POST",
+    body: JSON.stringify({
+      image: input.image || "node:22-slim",
+      command: input.command || "node scripts/riddleSpaPreviewServer.mjs build 3000",
+      port,
+      path: routePath,
+      readiness_path: input.readinessPath || routePath,
+      readiness_timeout: input.readinessTimeoutSec || 90,
+      wait_until: input.waitUntil || "domcontentloaded",
+      wait_for_selector: input.waitForSelector || "body",
+      navigation_timeout: input.navigationTimeoutSec || 60,
+      viewport: input.viewport,
+      timeout: timeoutSec,
+      script: input.script
+    })
+  });
+  const jobId = String(created.job_id || "");
+  const uploadUrl = String(created.upload_url || "");
+  if (!jobId || !uploadUrl) {
+    throw new Error(`Riddle server preview create response was missing job_id or upload_url.`);
+  }
+  const { scratch, tarball } = createTarball(input.directory, jobId, [
+    ".git",
+    "node_modules",
+    "test-results",
+    ...input.exclude || []
+  ]);
+  try {
+    const upload = await fetchFor(config)(uploadUrl, {
+      method: "PUT",
+      headers: { "Content-Type": "application/gzip" },
+      body: (0, import_node_fs5.readFileSync)(tarball)
+    });
+    if (!upload.ok) throw new RiddleApiError(uploadUrl, upload.status, await upload.text());
+  } finally {
+    (0, import_node_fs5.rmSync)(scratch, { recursive: true, force: true });
+  }
+  await riddleRequestJson(config, `/v1/server-preview/${jobId}/start`, {
+    method: "POST"
+  });
+  let job = null;
+  const attempts = input.pollAttempts || Math.ceil((timeoutSec + 90) / 2);
+  const intervalMs = input.pollIntervalMs || 2e3;
+  for (let index = 0; index < attempts; index += 1) {
+    job = await riddleRequestJson(config, `/v1/server-preview/${jobId}`);
+    if (isTerminalRiddleJobStatus(job.status)) break;
+    if (index + 1 < attempts) await new Promise((resolve) => setTimeout(resolve, intervalMs));
+  }
+  const status = job?.status ? String(job.status) : null;
+  const scriptError = scriptErrorFrom(job);
+  return {
+    ok: (status === "completed" || status === "complete") && !scriptError,
+    job_id: jobId,
+    status,
+    terminal: isTerminalRiddleJobStatus(status),
+    script_error: scriptError,
+    job
+  };
+}
 async function runRiddleScript(config, input) {
   if (!input.url?.trim()) throw new Error("url is required");
   if (!input.script?.trim()) throw new Error("script is required");
@@ -6544,6 +6626,7 @@ function createRiddleApiClient(config = {}) {
     requestJson: (pathname, init) => riddleRequestJson(config, pathname, init),
     deployStaticPreview: (directory, label) => deployRiddleStaticPreview(config, directory, label),
     runScript: (input) => runRiddleScript(config, input),
+    runServerPreview: (input) => runRiddleServerPreview(config, input),
     pollJob: (jobId, options) => pollRiddleJob(config, jobId, options)
   };
 }
@@ -6558,6 +6641,7 @@ function usage() {
     "  riddle-proof-loop respond --state-path <path> --decision <decision> --summary <text> [--payload-json <file|json|->]",
     "  riddle-proof-loop status --state-path <path>",
     "  riddle-proof-loop riddle-preview-deploy <build-dir> <label>",
+    "  riddle-proof-loop riddle-server-preview <directory> --script-file <file> [--path /route] [--wait-for-selector selector]",
     "  riddle-proof-loop riddle-run-script --url <url> --script-file <file> [--viewport 1280x720]",
     "  riddle-proof-loop riddle-poll <job-id> [--wait]",
     "  riddle-proof-loop doctor local [--codex-command <path>]",
@@ -6801,6 +6885,32 @@ async function main() {
 `);
     return;
   }
+  if (command === "riddle-server-preview") {
+    const directory = positional[1];
+    const scriptFile = optionString(options, "scriptFile");
+    if (!directory || !scriptFile) throw new Error("riddle-server-preview requires <directory> and --script-file.");
+    const result = await createRiddleApiClient(riddleClientConfig(options)).runServerPreview({
+      directory,
+      script: (0, import_node_fs6.readFileSync)(scriptFile, "utf-8"),
+      image: optionString(options, "image"),
+      command: optionString(options, "command"),
+      port: optionString(options, "port") ? Number(optionString(options, "port")) : void 0,
+      path: optionString(options, "path"),
+      readinessPath: optionString(options, "readinessPath"),
+      readinessTimeoutSec: optionString(options, "readinessTimeout") ? Number(optionString(options, "readinessTimeout")) : void 0,
+      waitForSelector: optionString(options, "waitForSelector"),
+      navigationTimeoutSec: optionString(options, "navigationTimeout") ? Number(optionString(options, "navigationTimeout")) : void 0,
+      viewport: parseRiddleViewport(optionString(options, "viewport")),
+      timeoutSec: optionString(options, "timeout") ? Number(optionString(options, "timeout")) : void 0,
+      pollAttempts: optionString(options, "pollAttempts") ? Number(optionString(options, "pollAttempts")) : void 0,
+      pollIntervalMs: optionString(options, "pollIntervalMs") ? Number(optionString(options, "pollIntervalMs")) : void 0,
+      exclude: optionString(options, "exclude")?.split(",").map((item) => item.trim()).filter(Boolean)
+    });
+    process.stdout.write(`${JSON.stringify(result, null, 2)}
+`);
+    process.exitCode = result.ok ? 0 : 1;
+    return;
+  }
   if (command === "riddle-run-script") {
     const url = optionString(options, "url");
     const scriptFile = optionString(options, "scriptFile");

package/dist/cli.js

@@ -2,23 +2,23 @@
 import {
   createRiddleApiClient,
   parseRiddleViewport
-} from "./chunk-UR6ADV4Y.js";
+} from "./chunk-3CVGVQTQ.js";
 import {
   createDisabledRiddleProofAgentAdapter,
   readRiddleProofRunStatus,
   runRiddleProofEngineHarness
-} from "./chunk-A2AWRZ5B.js";
+} from "./chunk-2FBF2UDZ.js";
+import "./chunk-MO24D3PY.js";
 import "./chunk-RFJ5BQF6.js";
+import "./chunk-3UHWI3FO.js";
+import {
+  createCheckpointResponseTemplate
+} from "./chunk-33XO42CY.js";
 import "./chunk-JFQXAJH2.js";
 import {
   createCodexExecAgentAdapter,
   runCodexExecAgentDoctor
 } from "./chunk-3266V3MO.js";
-import "./chunk-MO24D3PY.js";
-import "./chunk-3UHWI3FO.js";
-import {
-  createCheckpointResponseTemplate
-} from "./chunk-33XO42CY.js";
 import "./chunk-DUFDZJOF.js";
 
 // src/cli.ts
@@ -32,6 +32,7 @@ function usage() {
     "  riddle-proof-loop respond --state-path <path> --decision <decision> --summary <text> [--payload-json <file|json|->]",
     "  riddle-proof-loop status --state-path <path>",
     "  riddle-proof-loop riddle-preview-deploy <build-dir> <label>",
+    "  riddle-proof-loop riddle-server-preview <directory> --script-file <file> [--path /route] [--wait-for-selector selector]",
     "  riddle-proof-loop riddle-run-script --url <url> --script-file <file> [--viewport 1280x720]",
     "  riddle-proof-loop riddle-poll <job-id> [--wait]",
     "  riddle-proof-loop doctor local [--codex-command <path>]",
@@ -275,6 +276,32 @@ async function main() {
 `);
     return;
   }
+  if (command === "riddle-server-preview") {
+    const directory = positional[1];
+    const scriptFile = optionString(options, "scriptFile");
+    if (!directory || !scriptFile) throw new Error("riddle-server-preview requires <directory> and --script-file.");
+    const result = await createRiddleApiClient(riddleClientConfig(options)).runServerPreview({
+      directory,
+      script: readFileSync(scriptFile, "utf-8"),
+      image: optionString(options, "image"),
+      command: optionString(options, "command"),
+      port: optionString(options, "port") ? Number(optionString(options, "port")) : void 0,
+      path: optionString(options, "path"),
+      readinessPath: optionString(options, "readinessPath"),
+      readinessTimeoutSec: optionString(options, "readinessTimeout") ? Number(optionString(options, "readinessTimeout")) : void 0,
+      waitForSelector: optionString(options, "waitForSelector"),
+      navigationTimeoutSec: optionString(options, "navigationTimeout") ? Number(optionString(options, "navigationTimeout")) : void 0,
+      viewport: parseRiddleViewport(optionString(options, "viewport")),
+      timeoutSec: optionString(options, "timeout") ? Number(optionString(options, "timeout")) : void 0,
+      pollAttempts: optionString(options, "pollAttempts") ? Number(optionString(options, "pollAttempts")) : void 0,
+      pollIntervalMs: optionString(options, "pollIntervalMs") ? Number(optionString(options, "pollIntervalMs")) : void 0,
+      exclude: optionString(options, "exclude")?.split(",").map((item) => item.trim()).filter(Boolean)
+    });
+    process.stdout.write(`${JSON.stringify(result, null, 2)}
+`);
+    process.exitCode = result.ok ? 0 : 1;
+    return;
+  }
   if (command === "riddle-run-script") {
     const url = optionString(options, "url");
     const scriptFile = optionString(options, "scriptFile");

package/dist/engine-harness.js

@@ -2,9 +2,9 @@ import {
   createDisabledRiddleProofAgentAdapter,
   readRiddleProofRunStatus,
   runRiddleProofEngineHarness
-} from "./chunk-A2AWRZ5B.js";
-import "./chunk-RFJ5BQF6.js";
+} from "./chunk-2FBF2UDZ.js";
 import "./chunk-MO24D3PY.js";
+import "./chunk-RFJ5BQF6.js";
 import "./chunk-3UHWI3FO.js";
 import "./chunk-33XO42CY.js";
 import "./chunk-DUFDZJOF.js";