@riddledc/riddle-proof 0.8.63 → 0.8.65

package/README.md

@@ -179,6 +179,22 @@ or as a stronger proof base before a change loop.
 }
 ```
 
+For early proof authoring, `profile-suggest` can turn a route plus changed file,
+selector, and changed-text hints into a conservative draft profile:
+
+```sh
+riddle-proof-loop profile-suggest \
+  --route /games/signal-sprint \
+  --changed-files src/Games/SignalSprint.jsx,src/Games/SignalSprint.css \
+  --selectors .signal-sprint-start \
+  --changed-text-json '[{"selector":".signal-sprint-start","text":"Proof Run"}]' \
+  --format profile
+```
+
+The suggestion helper only drafts checks and artifacts; it does not produce a
+proof verdict. Run the generated profile with a local or hosted runner before
+treating the packet as evidence.
+
 Run a profile with the hosted Riddle runner:
 
 ```sh

package/dist/chunk-5Y4V2IXI.js

@@ -0,0 +1,178 @@
+import {
+  RIDDLE_PROOF_PROFILE_VERSION
+} from "./chunk-EX7TO4I5.js";
+
+// src/profile-suggestions.ts
+var RIDDLE_PROOF_PROFILE_SUGGESTIONS_VERSION = "riddle-proof.profile-suggestions.v1";
+var UI_FILE_PATTERN = /\.(css|html?|jsx?|tsx?|vue|svelte|mdx)$/i;
+var VISUAL_ASSET_PATTERN = /\.(avif|gif|jpe?g|png|svg|webp)$/i;
+function nonEmptyStrings(values) {
+  return Array.from(new Set(
+    (values || []).filter((value) => typeof value === "string").map((value) => value.trim()).filter(Boolean)
+  ));
+}
+function normalizeRoute(value) {
+  if (!value?.trim()) return void 0;
+  const trimmed = value.trim();
+  if (/^https?:\/\//i.test(trimmed)) return void 0;
+  return trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
+}
+function routeFromUrl(value) {
+  if (!value?.trim()) return void 0;
+  try {
+    const url = new URL(value);
+    return normalizeRoute(`${url.pathname}${url.search || ""}`);
+  } catch {
+    return void 0;
+  }
+}
+function slugify(value) {
+  return value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 80) || "suggested-profile";
+}
+function inferRouteFromFile(file) {
+  const normalized = file.replace(/\\/g, "/");
+  const routeMatch = normalized.match(/(?:^|\/)(?:pages|routes|app)\/(.+?)(?:\.[^.\/]+)?$/);
+  if (!routeMatch) return void 0;
+  const route = routeMatch[1].replace(/\/index$/i, "").replace(/\/page$/i, "").replace(/\[[^/\]]+\]/g, ":param");
+  return normalizeRoute(route || "/");
+}
+function inferRouteFromFiles(files) {
+  for (const file of files) {
+    const route = inferRouteFromFile(file);
+    if (route) return route;
+  }
+  return void 0;
+}
+function uniqueChecks(checks) {
+  const seen = /* @__PURE__ */ new Set();
+  return checks.filter((check) => {
+    const key = JSON.stringify(check);
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}
+function changedTextEntryText(entry) {
+  return typeof entry === "string" ? entry.trim() : (entry.expected_text || entry.text || "").trim();
+}
+function changedTextEntrySelector(entry) {
+  return typeof entry === "string" ? void 0 : entry.selector?.trim() || void 0;
+}
+function changedTextEntryLabel(entry) {
+  return typeof entry === "string" ? void 0 : entry.label?.trim() || void 0;
+}
+function suggestionProfileName(input, route, files) {
+  if (input.name?.trim()) return input.name.trim();
+  return `suggested-${slugify(route || files[0] || "profile")}`;
+}
+function defaultViewports(includeMobile) {
+  const viewports = [
+    { name: "desktop", width: 1280, height: 800 }
+  ];
+  if (includeMobile !== false) {
+    viewports.push({ name: "mobile", width: 390, height: 844 });
+  }
+  return viewports;
+}
+function suggestRiddleProofProfileChecks(input) {
+  const changedFiles = nonEmptyStrings(input.changed_files);
+  const selectors = nonEmptyStrings(input.selectors);
+  const changedText = input.changed_text || [];
+  const route = normalizeRoute(input.route) || inferRouteFromFiles(changedFiles) || routeFromUrl(input.url);
+  const uiFiles = changedFiles.filter((file) => UI_FILE_PATTERN.test(file));
+  const visualAssets = changedFiles.filter((file) => VISUAL_ASSET_PATTERN.test(file));
+  const warnings = [];
+  const suggestions = [];
+  const setupActions = [];
+  if (!route && !input.url?.trim()) {
+    warnings.push("No route or URL was supplied; the draft profile defaults to route /.");
+  }
+  if ((uiFiles.length || visualAssets.length) && !changedText.length && !selectors.length) {
+    warnings.push("UI or visual files changed, but no changed text or selectors were supplied; add focused checks before trusting this profile.");
+  }
+  const routeOrDefault = route || "/";
+  const routeChecks = [
+    { type: "route_loaded", expected_path: routeOrDefault }
+  ];
+  suggestions.push({
+    id: "route-loaded",
+    reason: "Every browser proof should first prove that the intended route loaded.",
+    checks: routeChecks
+  });
+  const hygieneChecks = [
+    { type: "no_fatal_console_errors" },
+    { type: "no_mobile_horizontal_overflow" }
+  ];
+  suggestions.push({
+    id: "runtime-hygiene",
+    reason: "UI changes should not introduce fatal console errors or mobile overflow.",
+    checks: hygieneChecks
+  });
+  for (const selector of selectors) {
+    suggestions.push({
+      id: `selector-${slugify(selector)}`,
+      reason: `Changed selector ${selector} should remain visible.`,
+      checks: [{ type: "selector_visible", selector }]
+    });
+  }
+  for (const entry of changedText) {
+    const text = changedTextEntryText(entry);
+    if (!text) continue;
+    const selector = changedTextEntrySelector(entry);
+    const label = changedTextEntryLabel(entry);
+    const check = selector ? { type: "selector_text_visible", selector, text, label } : { type: "text_visible", text, label };
+    suggestions.push({
+      id: `text-${slugify(`${selector || "page"}-${text}`)}`,
+      reason: selector ? `Expected text should be visible inside ${selector}.` : "Expected text should be visible on the route.",
+      checks: [check]
+    });
+  }
+  if (input.include_screenshot !== false && (uiFiles.length || visualAssets.length || selectors.length || changedText.length)) {
+    setupActions.push({ type: "screenshot", label: "suggested-proof-screenshot", full_page: true });
+    suggestions.push({
+      id: "screenshot-artifact",
+      reason: "A screenshot artifact keeps the proof packet inspectable by humans and hosted renderers.",
+      checks: [],
+      setup_actions: setupActions
+    });
+  }
+  const checks = uniqueChecks(suggestions.flatMap((suggestion) => suggestion.checks));
+  const target = {
+    ...input.url?.trim() ? { url: input.url.trim() } : { route: routeOrDefault },
+    viewports: defaultViewports(input.include_mobile),
+    setup_actions: setupActions.length ? setupActions : void 0
+  };
+  const profile = {
+    version: RIDDLE_PROOF_PROFILE_VERSION,
+    name: suggestionProfileName(input, routeOrDefault, changedFiles),
+    target,
+    checks,
+    artifacts: ["screenshot", "console", "proof_json"],
+    baseline_policy: "invariant_only",
+    failure_policy: {
+      product_regression: "fail",
+      proof_insufficient: "review",
+      environment_blocked: "neutral",
+      configuration_error: "fail",
+      needs_human_review: "review"
+    },
+    metadata: {
+      suggestion_input: {
+        changed_files: changedFiles,
+        selectors,
+        changed_text_count: changedText.length
+      }
+    }
+  };
+  return {
+    version: RIDDLE_PROOF_PROFILE_SUGGESTIONS_VERSION,
+    profile,
+    suggestions,
+    warnings
+  };
+}
+
+export {
+  RIDDLE_PROOF_PROFILE_SUGGESTIONS_VERSION,
+  suggestRiddleProofProfileChecks
+};

package/dist/{chunk-DI2XNGEZ.js → chunk-B2DP2LET.js}

@@ -5,6 +5,7 @@ import { tmpdir } from "os";
 import path from "path";
 var DEFAULT_RIDDLE_API_BASE_URL = "https://api.riddledc.com";
 var DEFAULT_RIDDLE_API_KEY_FILE = "/tmp/riddle-api-key";
+var RIDDLE_UNSUBMITTED_WAKE_HINT = "hosted worker may still be waking or waiting for a lease";
 var RiddleApiError = class extends Error {
   constructor(pathname, status, body) {
     super(`Riddle API ${pathname} failed HTTP ${status}: ${body}`);
@@ -472,9 +473,10 @@ function buildPollSnapshot(jobId, job, input) {
 function pollMessage(snapshot, timedOut) {
   if (!timedOut) return void 0;
   const submitted = snapshot.submitted_at || "not submitted";
+  const wakeHint = snapshot.running_without_submission && !snapshot.created_at && !snapshot.submitted_at ? ` ${RIDDLE_UNSUBMITTED_WAKE_HINT}.` : "";
   const queue = snapshot.queue_elapsed_ms !== null ? ` queue_elapsed_ms=${snapshot.queue_elapsed_ms}` : "";
   const preSubmit = snapshot.pre_submission_elapsed_ms > 0 ? ` pre_submission_elapsed_ms=${snapshot.pre_submission_elapsed_ms}` : "";
-  return `Riddle job ${snapshot.job_id} did not reach a terminal status after ${snapshot.attempt} poll attempts; status=${snapshot.status || "unknown"} submitted_at=${submitted}.${queue}${preSubmit}`;
+  return `Riddle job ${snapshot.job_id} did not reach a terminal status after ${snapshot.attempt} poll attempts; status=${snapshot.status || "unknown"} submitted_at=${submitted}.${wakeHint}${queue}${preSubmit}`;
 }
 async function pollRiddleJob(config, jobId, options = {}) {
   if (!jobId?.trim()) throw new Error("jobId is required");
@@ -585,6 +587,7 @@ function createRiddleApiClient(config = {}) {
 export {
   DEFAULT_RIDDLE_API_BASE_URL,
   DEFAULT_RIDDLE_API_KEY_FILE,
+  RIDDLE_UNSUBMITTED_WAKE_HINT,
   RiddleApiError,
   resolveRiddleApiKeySource,
   resolveRiddleApiKey,

package/dist/{chunk-DDAV6D6K.js → chunk-JPRKO2DH.js}

@@ -1,13 +1,17 @@
 import {
+  RIDDLE_UNSUBMITTED_WAKE_HINT,
   createRiddleApiClient,
   isTerminalRiddleJobStatus,
   parseRiddleViewport
-} from "./chunk-DI2XNGEZ.js";
+} from "./chunk-B2DP2LET.js";
 import {
   RIDDLE_PROOF_PR_COMMENT_MARKER,
   buildRiddleProofPrCommentMarkdown,
   summarizeRiddleProofPrComment
 } from "./chunk-RZ3GXSXQ.js";
+import {
+  suggestRiddleProofProfileChecks
+} from "./chunk-5Y4V2IXI.js";
 import {
   RIDDLE_PROOF_PROFILE_EVIDENCE_VERSION,
   applyRiddleProofProfileArtifactCompleteness,
@@ -55,6 +59,8 @@ var KNOWN_CLI_OPTIONS = /* @__PURE__ */ new Set([
   "candidatesJson",
   "checkpointMode",
   "checkpointVisibility",
+  "changedFiles",
+  "changedTextJson",
   "codexCommand",
   "codexFullAuto",
   "codexHome",
@@ -76,6 +82,8 @@ var KNOWN_CLI_OPTIONS = /* @__PURE__ */ new Set([
   "help",
   "hostedRiddle",
   "image",
+  "includeMobile",
+  "includeScreenshot",
   "input",
   "inputDir",
   "inputFile",
@@ -86,6 +94,7 @@ var KNOWN_CLI_OPTIONS = /* @__PURE__ */ new Set([
   "jobId",
   "localCore",
   "maxIterations",
+  "name",
   "navigationTimeout",
   "output",
   "outputDir",
@@ -118,6 +127,7 @@ var KNOWN_CLI_OPTIONS = /* @__PURE__ */ new Set([
   "runResponse",
   "runner",
   "scriptFile",
+  "selectors",
   "sourceKind",
   "splitViewports",
   "stateDir",
@@ -153,6 +163,7 @@ function usage() {
     "  riddle-proof-loop run-profile --profile <file|json|-> --url <base-url> [--base-url <base-url>] [--runner riddle] [--viewport-name <name[,name...]>] [--strict true|false; default false] [--split-viewports true|false; default false] [--balance-preflight true|false; default true] [--poll-attempts n] [--output <dir>|--output-dir <dir>] [--result-format json|compact-json|summary|none; default json] [--quiet]",
     "  riddle-proof-loop run-profile aggregate --profile <file|json|-> --url <base-url> [--base-url <base-url>] --input-dir <dir>|--inputs <path[,path...]> [--output <dir>|--output-dir <dir>] [--result-format json|compact-json|summary|none; default json]",
     "  riddle-proof-loop run-profile recover --profile <file|json|-> --url <base-url> [--base-url <base-url>] --job <job-id> [--viewport-name <name[,name...]>] [--output <dir>|--output-dir <dir>] [--result-format json|compact-json|summary|none; default json]",
+    "  riddle-proof-loop profile-suggest --route /path|--url <url> [--changed-files a,b] [--selectors .a,.b] [--changed-text-json <file|json|->] [--format json|profile]",
     "  riddle-proof-loop regression-pack run [--pack oc-flow-regression|--pack-file <file>] [--local-core true|false; default true] [--hosted-riddle true|false; default false] [--format json|markdown|compact-json; default json] [--output <dir>|--output-dir <dir>]",
     "  riddle-proof-loop pr-comment --proof-dir <dir>|--run-response <file> [--result-json <file>] --pr <number|url> [--repo owner/name] [--dry-run] [--body-file <file>] [--comment-mode update|append]",
     "  riddle-proof-loop profile-body-assertions --artifact <file|url|-> --candidates-json <file|json|-> [--required-json <file|json|->] [--format json|body-contains]",
@@ -207,6 +218,10 @@ function optionString(options, key) {
   const value = options[key];
   return typeof value === "string" && value.trim() ? value.trim() : void 0;
 }
+function optionStringList(options, key) {
+  const value = optionString(options, key);
+  return value ? value.split(",").map((item) => item.trim()).filter(Boolean) : void 0;
+}
 function optionBoolean(options, key) {
   const value = options[key];
   if (typeof value === "undefined") return void 0;
@@ -940,7 +955,7 @@ function formatByteCount(bytes) {
 }
 function riddlePollProgressLine(snapshot) {
   const submittedAt = snapshot.submitted_at || "not-submitted";
-  const queuePart = snapshot.running_without_submission ? ` waiting_for_submit=${formatPollDuration(snapshot.pre_submission_elapsed_ms)}${snapshot.queue_elapsed_ms !== null ? ` queued_for=${formatPollDuration(snapshot.queue_elapsed_ms)}` : ""}` : snapshot.queue_elapsed_ms !== null ? ` queue=${formatPollDuration(snapshot.queue_elapsed_ms)}` : "";
+  const queuePart = snapshot.running_without_submission ? ` waiting_for_worker_submit=${formatPollDuration(snapshot.pre_submission_elapsed_ms)} worker_wake=possible${snapshot.queue_elapsed_ms !== null ? ` queued_for=${formatPollDuration(snapshot.queue_elapsed_ms)}` : ""}` : snapshot.queue_elapsed_ms !== null ? ` queue=${formatPollDuration(snapshot.queue_elapsed_ms)}` : "";
   const terminalPart = snapshot.terminal ? " terminal=true" : "";
   return [
     "[riddle-poll]",
@@ -1047,6 +1062,11 @@ function readJsonValue(value, label) {
   }
   return parsed;
 }
+function readJsonAnyValue(value, label) {
+  if (!value) throw new Error(`${label} is required.`);
+  const raw = value === "-" ? readStdin() : existsSync(value) ? readFileSync(value, "utf-8") : value;
+  return JSON.parse(raw);
+}
 function readOptionalJsonRecord(value, label) {
   if (!value) return void 0;
   return readJsonValue(value, label);
@@ -1361,7 +1381,7 @@ function profileRiddleJobMarkdown(result) {
     lines.push("- artifact recovery: used artifacts endpoint after non-terminal poll");
   }
   if (retryCount !== void 0 && retryCount > 0) {
-    lines.push(`- retry recovery: replaced ${retryCount} unsubmitted job${retryCount === 1 ? "" : "s"}${staleJobIds.length ? ` (${staleJobIds.map((value) => markdownInlineCode(value)).join(", ")})` : ""}`);
+    lines.push(`- retry recovery: replaced ${retryCount} unsubmitted hosted job${retryCount === 1 ? "" : "s"}${staleJobIds.length ? ` (${staleJobIds.map((value) => markdownInlineCode(value)).join(", ")})` : ""}; ${RIDDLE_UNSUBMITTED_WAKE_HINT}`);
   }
   for (const job of splitJobs.slice(0, 12)) {
     const viewport = cliString(job.viewport) || "viewport";
@@ -4446,7 +4466,7 @@ async function runSingleRiddleProfileForCli(profile, options, input) {
       }
       staleJobIds.push(jobId);
       if (options.quiet !== true) {
-        process.stderr.write(`[riddle-poll] ${jobId} stayed unsubmitted for ${formatPollDuration(poll.poll?.pre_submission_elapsed_ms)}; retrying hosted run ${attempt + 1}/${retryLimit}
+        process.stderr.write(`[riddle-poll] ${jobId} stayed unsubmitted for ${formatPollDuration(poll.poll?.pre_submission_elapsed_ms)}; ${RIDDLE_UNSUBMITTED_WAKE_HINT}; retrying hosted run ${attempt + 1}/${retryLimit}
 `);
       }
       continue;
@@ -4747,6 +4767,34 @@ async function main() {
     process.exitCode = result.ok ? 0 : 1;
     return;
   }
+  if (command === "profile-suggest") {
+    const changedTextJson = optionString(options, "changedTextJson");
+    const changedText = changedTextJson ? readJsonAnyValue(changedTextJson, "--changed-text-json") : void 0;
+    if (changedText !== void 0 && !Array.isArray(changedText)) {
+      throw new Error("--changed-text-json must be a JSON array.");
+    }
+    const result = suggestRiddleProofProfileChecks({
+      name: optionString(options, "name"),
+      route: optionString(options, "route"),
+      url: optionString(options, "url"),
+      changed_files: optionStringList(options, "changedFiles"),
+      selectors: optionStringList(options, "selectors"),
+      changed_text: changedText,
+      include_mobile: optionBoolean(options, "includeMobile"),
+      include_screenshot: optionBoolean(options, "includeScreenshot")
+    });
+    const format = optionString(options, "format") || "json";
+    if (format === "profile") {
+      process.stdout.write(`${JSON.stringify(result.profile, null, 2)}
+`);
+    } else if (format === "json") {
+      process.stdout.write(`${JSON.stringify(result, null, 2)}
+`);
+    } else {
+      throw new Error("--format must be json or profile.");
+    }
+    return;
+  }
   if (command === "profile-body-assertions") {
     const artifactText = await readTextValue(optionString(options, "artifact") ?? optionString(options, "input"), "--artifact");
     const candidates = readOptionalJsonStringArray(optionString(options, "candidatesJson") ?? optionString(options, "candidateJson"), "--candidates-json") ?? [];

package/dist/cli/index.js

@@ -1,6 +1,7 @@
-import "../chunk-DDAV6D6K.js";
-import "../chunk-DI2XNGEZ.js";
+import "../chunk-JPRKO2DH.js";
+import "../chunk-B2DP2LET.js";
 import "../chunk-RZ3GXSXQ.js";
+import "../chunk-5Y4V2IXI.js";
 import "../chunk-EX7TO4I5.js";
 import "../chunk-P4BHU5NM.js";
 import "../chunk-NMQIWBSB.js";