@deeeed/metamask-harness 0.23.1 → 0.25.0

package/dist/run-recording.js

@@ -31,23 +31,25 @@ async function startRecipeRecording(adapter, projectRoot, artifactsDir, options)
   }
   const recordArgs = ["record", "--framed", "--pid", String(pid)];
   const relativePath = "videos/full-run.mp4";
-  const outputPath = path.join(artifactsDir, relativePath);
-  fs.mkdirSync(path.dirname(outputPath), { recursive: true });
-  fs.rmSync(outputPath, { force: true });
-  const child = spawn(captureHelperPath(), [...recordArgs, "--output", outputPath], {
+  const stage = preparePrivateRecordingStage(artifactsDir, relativePath);
+  const child = spawn(captureHelperPath(), [...recordArgs, "--output", stage.stagedOutputPath], {
     cwd: projectRoot,
     env: process.env,
     stdio: ["pipe", "pipe", "pipe"]
   });
   const recording = {
     child,
-    outputPath,
+    outputPath: stage.outputPath,
+    stagedOutputPath: stage.stagedOutputPath,
+    stagingDir: stage.stagingDir,
     relativePath,
     pid,
     stdout: "",
     stderr: "",
     exited: false,
     exitCode: null,
+    frameReady: false,
+    finalized: false,
     stderrBuffer: "",
     pendingSnapshots: /* @__PURE__ */ new Map()
   };
@@ -69,15 +71,25 @@ async function startRecipeRecording(adapter, projectRoot, artifactsDir, options)
     activeRecordingsByPid.delete(recording.pid);
     rejectPendingSnapshots(recording, new Error(`capture-helper recording exited before snapshot completed (code=${exitCode ?? "unknown"})`));
   });
-  await sleep(750);
+  await waitForRecordingReady(recording, 15e3);
   if (recording.exited) {
-    console.error(
-      `WARN: capture-helper record exited before the recipe started (code=${recording.exitCode ?? "unknown"}): ${recording.stderr || recording.stdout}`
+    cleanupRecordingStage(recording);
+    throw new Error(
+      `capture-helper exited before recording its first frame (code=${recording.exitCode ?? "unknown"}): ${recording.stderr || recording.stdout}`
+    );
+  }
+  if (!recording.frameReady) {
+    try {
+      await stopRecordingProcess(recording);
+    } finally {
+      cleanupRecordingStage(recording);
+    }
+    throw new Error(
+      `capture-helper did not record a frame within 15000ms: ${recording.stderr || recording.stdout || "no recorder output"}`
     );
-    return void 0;
   }
   activeRecordingsByPid.set(pid, recording);
-  console.error(`INFO: recording recipe video with capture-helper pid=${pid} output=${outputPath}`);
+  console.error(`INFO: recording recipe video with capture-helper pid=${pid} output=${recording.outputPath}`);
   return recording;
 }
 async function captureActiveRecipeRecordingSnapshot(pid, outputPath, timeoutMs = 3e4) {
@@ -101,8 +113,36 @@ async function captureActiveRecipeRecordingSnapshot(pid, outputPath, timeoutMs =
   });
 }
 async function stopRecipeRecording(recording, result) {
-  if (!recording) return;
-  if (!recording.exited) {
+  if (!recording || recording.finalized) return;
+  recording.finalized = true;
+  try {
+    await stopRecordingProcess(recording);
+  } catch (error) {
+    cleanupRecordingStage(recording);
+    if (result) removeRecordingArtifactFromManifest(result, recording.relativePath);
+    throw error;
+  }
+  const validation = validateRecordingArtifact(recording);
+  if (validation.ok === false) {
+    cleanupRecordingStage(recording);
+    if (result) removeRecordingArtifactFromManifest(result, recording.relativePath);
+    throw new Error(
+      `capture-helper recording did not produce a usable video artifact: ${validation.reason}`
+    );
+  }
+  try {
+    publishPrivateRecording(recording);
+  } catch (error) {
+    cleanupRecordingStage(recording);
+    if (result) removeRecordingArtifactFromManifest(result, recording.relativePath);
+    throw new Error(
+      `capture-helper recording could not safely publish ${recording.outputPath}: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+  if (result) addRecordingArtifactToManifest(result, recording);
+}
+async function stopRecordingProcess(recording) {
+  if (!recording.exited && !recording.child.stdin.destroyed) {
     recording.child.stdin.end("stop\n");
     await waitForRecordingExit(recording, 15e3);
   }
@@ -114,33 +154,33 @@ async function stopRecipeRecording(recording, result) {
     recording.child.kill("SIGTERM");
     await waitForRecordingExit(recording, 3e3);
   }
-  const validation = validateRecordingArtifact(recording);
-  if (validation.ok === false) {
-    try {
-      fs.rmSync(recording.outputPath, { force: true });
-    } catch (error) {
-      console.error(
-        `WARN: could not remove unusable capture-helper video ${recording.outputPath}: ${error instanceof Error ? error.message : String(error)}`
-      );
-    }
-    console.error(
-      `WARN: capture-helper recording did not produce a usable video artifact: ${validation.reason}`
-    );
-    if (result) removeRecordingArtifactFromManifest(result, recording.relativePath);
-    return;
+  if (!recording.exited) {
+    recording.child.kill("SIGKILL");
+    await waitForRecordingExit(recording, 2e3);
+  }
+  if (!recording.exited) {
+    throw new Error(`capture-helper recording process did not exit: pid=${recording.child.pid ?? "unknown"}`);
   }
-  if (result) addRecordingArtifactToManifest(result, recording);
 }
 async function waitForRecordingExit(recording, timeoutMs) {
   if (recording.exited) return;
   await new Promise((resolve) => {
-    const timer = setTimeout(resolve, timeoutMs);
-    recording.child.once("close", () => {
+    const finish = () => {
       clearTimeout(timer);
+      recording.child.removeListener("close", finish);
       resolve();
-    });
+    };
+    const timer = setTimeout(finish, timeoutMs);
+    recording.child.once("close", finish);
+    if (recording.exited) finish();
   });
 }
+async function waitForRecordingReady(recording, timeoutMs) {
+  const deadline = Date.now() + timeoutMs;
+  while (!recording.frameReady && !recording.exited && Date.now() < deadline) {
+    await sleep(50);
+  }
+}
 function handleRecordingStderr(recording, chunk) {
   recording.stderrBuffer += chunk;
   let newlineIndex = recording.stderrBuffer.indexOf("\n");
@@ -160,6 +200,9 @@ function handleRecordingEventLine(recording, line) {
   } catch {
     return;
   }
+  if (event.type === "info" && typeof event.msg === "string" && /^record frames=[1-9]\d*$/.test(event.msg)) {
+    recording.frameReady = true;
+  }
   const output = typeof event.output === "string" ? event.output : void 0;
   if (!output) return;
   const pending = recording.pendingSnapshots.get(output);
@@ -184,36 +227,39 @@ function rejectPendingSnapshots(recording, error) {
   recording.pendingSnapshots.clear();
 }
 function validateRecordingArtifact(recording) {
-  if (!fs.existsSync(recording.outputPath)) {
-    return { ok: false, reason: `missing output ${recording.outputPath}` };
+  if (!fs.existsSync(recording.stagedOutputPath)) {
+    return { ok: false, reason: `missing output ${recording.stagedOutputPath}` };
   }
-  const size = fs.statSync(recording.outputPath).size;
-  if (size === 0) {
-    return { ok: false, reason: `empty output ${recording.outputPath}` };
+  const info = fs.lstatSync(recording.stagedOutputPath);
+  if (info.isSymbolicLink() || !info.isFile()) {
+    return { ok: false, reason: `output is not a safe regular file ${recording.stagedOutputPath}` };
+  }
+  if (info.size === 0) {
+    return { ok: false, reason: `empty output ${recording.stagedOutputPath}` };
   }
   const recorderOutput = `${recording.stdout}
 ${recording.stderr}`;
   if (!recorderOutput.includes("record_complete")) {
     return {
       ok: false,
-      reason: `capture-helper did not report record_complete for ${recording.outputPath}: ${recorderOutput.trim() || "no recorder output"}`
+      reason: `capture-helper did not report record_complete for ${recording.stagedOutputPath}: ${recorderOutput.trim() || "no recorder output"}`
     };
   }
   const ffprobe = spawnSync(
     "ffprobe",
-    ["-hide_banner", "-v", "error", "-show_entries", "format=duration", "-of", "default=noprint_wrappers=1:nokey=1", recording.outputPath],
+    ["-hide_banner", "-v", "error", "-show_entries", "format=duration", "-of", "default=noprint_wrappers=1:nokey=1", recording.stagedOutputPath],
     { encoding: "utf8" }
   );
   if (ffprobe.error && ffprobe.error.code === "ENOENT") {
     return { ok: true };
   }
   if (ffprobe.error) {
-    return { ok: false, reason: `ffprobe failed for ${recording.outputPath}: ${ffprobe.error.message}` };
+    return { ok: false, reason: `ffprobe failed for ${recording.stagedOutputPath}: ${ffprobe.error.message}` };
   }
   if (ffprobe.status !== 0) {
     return {
       ok: false,
-      reason: `invalid MP4 ${recording.outputPath}: ${ffprobe.stderr.trim() || ffprobe.stdout.trim() || `ffprobe exited ${ffprobe.status}`}`
+      reason: `invalid MP4 ${recording.stagedOutputPath}: ${ffprobe.stderr.trim() || ffprobe.stdout.trim() || `ffprobe exited ${ffprobe.status}`}`
     };
   }
   const durationSeconds = Number(ffprobe.stdout.trim());
@@ -222,6 +268,77 @@ ${recording.stderr}`;
   }
   return { ok: true };
 }
+function preparePrivateRecordingStage(artifactsDir, relativePath) {
+  const artifactsRoot = path.resolve(artifactsDir);
+  const outputPath = path.resolve(artifactsRoot, relativePath);
+  if (!outputPath.startsWith(`${artifactsRoot}${path.sep}`)) {
+    throw new Error(`Refusing recording artifact outside artifacts dir: ${relativePath}`);
+  }
+  fs.mkdirSync(artifactsRoot, { recursive: true });
+  ensureRecordingParent(artifactsRoot, path.dirname(outputPath));
+  refuseUnsafeRecordingDestination(outputPath);
+  const stagingDir = fs.mkdtempSync(path.join(artifactsRoot, ".extension-recording-"));
+  fs.chmodSync(stagingDir, 448);
+  return {
+    outputPath,
+    stagedOutputPath: path.join(stagingDir, "full-run.mp4"),
+    stagingDir
+  };
+}
+function ensureRecordingParent(artifactsRoot, parent) {
+  const relative = path.relative(artifactsRoot, parent);
+  let current = artifactsRoot;
+  for (const segment of relative.split(path.sep).filter(Boolean)) {
+    current = path.join(current, segment);
+    const info = lstatIfPresent(current);
+    if (!info) {
+      fs.mkdirSync(current, { mode: 448 });
+      continue;
+    }
+    if (info.isSymbolicLink() || !info.isDirectory()) {
+      throw new Error(`Refusing recording artifact parent that is not a real directory: ${current}`);
+    }
+  }
+}
+function refuseUnsafeRecordingDestination(outputPath) {
+  const info = lstatIfPresent(outputPath);
+  if (!info) return;
+  if (info.isSymbolicLink()) {
+    throw new Error(`Refusing recording artifact destination symlink: ${outputPath}`);
+  }
+  if (!info.isFile()) {
+    throw new Error(`Refusing recording artifact destination that is not a regular file: ${outputPath}`);
+  }
+}
+function lstatIfPresent(filePath) {
+  try {
+    return fs.lstatSync(filePath);
+  } catch (error) {
+    if (error.code === "ENOENT") return void 0;
+    throw error;
+  }
+}
+function publishPrivateRecording(recording) {
+  const descriptor = fs.openSync(
+    recording.stagedOutputPath,
+    fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0)
+  );
+  try {
+    const info = fs.fstatSync(descriptor);
+    if (!info.isFile()) {
+      throw new Error(`Captured recording is not a safe regular file: ${recording.stagedOutputPath}`);
+    }
+    fs.fchmodSync(descriptor, 384);
+    refuseUnsafeRecordingDestination(recording.outputPath);
+    fs.renameSync(recording.stagedOutputPath, recording.outputPath);
+  } finally {
+    fs.closeSync(descriptor);
+  }
+  cleanupRecordingStage(recording);
+}
+function cleanupRecordingStage(recording) {
+  fs.rmSync(recording.stagingDir, { recursive: true, force: true });
+}
 function addRecordingArtifactToManifest(result, recording) {
   const manifestPath = result.artifactManifestPath;
   if (!manifestPath || !fs.existsSync(manifestPath)) {

package/library/actions/core/perps/_controller.mjs

@@ -618,6 +618,60 @@ export function redactPosition(position) {
   };
 }
 
+/**
+ * Wrap a controller rejection so its typed code survives as data.
+ *
+ * `expect_error` used to match by substring against the message, which meant a
+ * message that merely mentioned a code — or contained a longer code with the
+ * expected one as a prefix — matched wrongly. Carrying the code on the error
+ * lets the comparison be exact.
+ *
+ * @param params - Rejection details.
+ * @param params.action - Action name, for the message.
+ * @param params.detail - Human context for the message.
+ * @param params.code - The controller's typed error code.
+ * @returns An error carrying `perpsErrorCode`.
+ */
+export function controllerRejection(params) {
+  const { action, detail, code } = params;
+  const error = new Error(`${action} was rejected: ${code}${detail ? ` (${detail})` : ''}`);
+  error.perpsErrorCode = code;
+  return error;
+}
+
+/**
+ * Read an optional node param, treating an unset template as absent.
+ *
+ * Recipes are static JSON, so an optional parameter that a caller leaves at its
+ * default arrives as an empty string rather than being omitted. Passing that
+ * through as a set-but-empty value is how a plain order ends up carrying an
+ * empty TP/SL size, which the controller then rejects as invalid. Whitespace is
+ * trimmed for the same reason.
+ *
+ * @param node - The recipe node.
+ * @param snake - snake_case param name.
+ * @param camel - camelCase alias.
+ * @returns The value as a string, or undefined when the node did not set it.
+ */
+export function optionalParam(node, snake, camel) {
+  const normalize = (value) => {
+    if (value === undefined || value === null) {
+      return undefined;
+    }
+    const text = String(value).trim();
+    return text.length === 0 ? undefined : text;
+  };
+  return normalize(node?.[snake]) ?? normalize(node?.[camel]);
+}
+
+export function optionalBooleanParam(node, snake, camel) {
+  const value = optionalParam(node, snake, camel);
+  if (value === undefined) return undefined;
+  if (value.toLowerCase() === 'true') return true;
+  if (value.toLowerCase() === 'false') return false;
+  throw new Error(`${snake} must be true or false; got ${value}.`);
+}
+
 export function redactOrder(order) {
   return {
     coin: order.coin ?? order.symbol ?? null,
@@ -691,16 +745,95 @@ async function disconnectController(exitCode) {
   }
 }
 
+/**
+ * Read the rejection a node expects, if any.
+ *
+ * @param input - Adapter input (node.expect_error / node.expectError).
+ * @returns The expected error token, or undefined when the node expects success.
+ */
+function expectedErrorFor(input) {
+  const node = input?.node ?? {};
+  for (const key of ['expect_error', 'expectError']) {
+    const value = node[key];
+    if (typeof value === 'string' && value.trim().length > 0) {
+      return value.trim();
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Run a Core perps adapter, honouring an expected rejection.
+ *
+ * Most nodes assert that an operation succeeds. A controller's refusals are part
+ * of its contract too — that a partial size below the asset's precision, or a
+ * TP/SL linkage the venue cannot express, is rejected with a typed error and
+ * before any side effect. Without `expect_error` those can only be proven by a
+ * bespoke script, because every action here throws on failure.
+ *
+ * With `expect_error` set, a throw whose message carries the expected token is
+ * the passing outcome: the rejection is written out as evidence and the process
+ * exits 0. Anything else fails — a different error, or the operation succeeding
+ * when it should have been refused. The success case is checked explicitly
+ * rather than left to fall through, so a contract that silently stops rejecting
+ * is caught rather than reported as a pass.
+ *
+ * Actions surface a controller's `{ success: false, error }` result by throwing
+ * with the code in the message (see place_order.mjs), so a substring match
+ * covers both that shape and a genuine throw.
+ *
+ * When the param is absent this is byte-identical to the previous behaviour.
+ *
+ * @param callback - The adapter body, receiving the loaded input.
+ */
 export async function runAdapter(callback) {
   const input = await loadInput();
+  const expectedError = expectedErrorFor(input);
   let exitCode = 0;
   try {
-    await writeOutput(input, await callback(input));
+    const output = await callback(input);
+    if (expectedError) {
+      // Not thrown: a rejection asserted here must not be satisfied by the
+      // message this branch would itself produce.
+      exitCode = 1;
+      process.stderr.write(
+        `[core/perps] ${input.action} expected rejection ${expectedError}, but it succeeded.\n`,
+      );
+    } else {
+      await writeOutput(input, output);
+    }
   } catch (error) {
-    exitCode = 1;
-    // Surface the failure; still tear down so a half-open WebSocket from a
-    // failed write doesn't leave the process wedged open.
-    process.stderr.write(`[core/perps] adapter failed: ${fmtError(error)}\n`);
+    const message = error?.message ?? String(error);
+    // A typed proof requires the code as data. Matching on the message was a
+    // weaker check wearing the same name: an adapter's own error, or any text
+    // that merely mentioned a code, could satisfy it. Only a rejection the
+    // action tagged with the controller's code counts, compared exactly — so a
+    // proof cannot pass on a failure the controller never issued.
+    const code = error?.perpsErrorCode;
+    if (expectedError && code === expectedError) {
+      await writeOutput(input, {
+        action: input.action,
+        source: 'expect_error',
+        rejected: true,
+        matched: true,
+        matchedOn: 'code',
+        expectedError,
+        actualErrorCode: code,
+        actualError: message,
+      });
+    } else {
+      exitCode = 1;
+      if (expectedError) {
+        process.stderr.write(
+          code === undefined
+            ? `[core/perps] ${input.action} expected rejection ${expectedError}, but the failure carries no controller error code — it did not come from the controller.\n`
+            : `[core/perps] ${input.action} expected rejection ${expectedError}, but the controller rejected with ${code}.\n`,
+        );
+      }
+      // Surface the failure; still tear down so a half-open WebSocket from a
+      // failed write doesn't leave the process wedged open.
+      process.stderr.write(`[core/perps] adapter failed: ${fmtError(error)}\n`);
+    }
   } finally {
     await disconnectController(exitCode);
   }