Open-source design agent: on-brand stills, decks, diagrams, charts and motion graphics from a chat thread, built on Deep Agents.
JavaScript agentagentsai-agentdeepagentsdesignhyperframeslanggraphmanaged-agentsmotion-graphicspaperslackvideo
#!/usr/bin/env node
// artifact-contract.mjs — fail-closed intake and completion checks for visual work, and a measurement
// of the files that were actually produced.
//
// Usage:
// node /workspace/tools/artifact-contract.mjs --contract projects/<slug>/artifact-contract.json --phase plan
// node /workspace/tools/artifact-contract.mjs --contract projects/<slug>/artifact-contract.json --phase final
// node /workspace/tools/artifact-contract.mjs --layers projects/<slug>/layer-manifest.json
// node /workspace/tools/artifact-contract.mjs --expect <path>:<W>x<H> [--expect <path>:<W>x<H>@<seconds> ...] [--json]
//
// --expect measures each output: it must exist, be non-empty and decode as the format its extension
// names, at exactly W x H. Stills (PNG, JPEG, WebP) are read from their header bytes, no image
// library needed. A video expectation adds @<seconds>: ffprobe must report that duration within one
// frame, and the first and last frames must not be blank (frame 0 is the poster and the thumbnail);
// --allow-blank-ends accepts a fade from or to a flat ground that the person asked for.
// In --phase final, a contract whose output names a `path` is measured the same way.
//
// Relative paths resolve against --root (default: the folder holding tools/, i.e. /workspace) and
// nothing outside it is read.
// Exit: 0 pass · 1 findings (a missing or wrong output, an invalid contract) · 2 the check could not
// run (bad arguments, unreadable contract file, ffprobe/ffmpeg missing).
import { lstatSync, readFileSync, statSync } from "node:fs";
import { spawnSync } from "node:child_process";
import { extname, isAbsolute, relative, resolve, sep } from "node:path";
import { EXIT, ToolingError, WORKSPACE, isMain, parseFlags, runCli } from "./toolchain.mjs";
let ROOT = WORKSPACE;
const MAX_DIMENSION = 16_384;
const MAX_ITEMS = 250;
const MAX_TEXT = 2_000;
const MAX_PATH = 512;
const problems = [];
function fail(message) {
problems.push(message);
}
function confinedFile(input, label) {
if (typeof input !== "string" || input.length === 0 || input.length > MAX_PATH) {
throw new ToolingError(`${label} must be a non-empty path under ${ROOT}`);
}
const file = resolve(ROOT, input);
const fromRoot = relative(ROOT, file);
if (fromRoot.startsWith(`..${sep}`) || isAbsolute(fromRoot)) {
throw new ToolingError(`${label} escapes the workspace root: ${input}`);
}
let stats;
try {
stats = lstatSync(file);
} catch {
throw new ToolingError(`${label} is not a file: ${input}`);
}
if (stats.isSymbolicLink()) throw new ToolingError(`${label} must not be a symbolic link: ${input}`);
if (!stats.isFile()) throw new ToolingError(`${label} is not a file: ${input}`);
return file;
}
function confinedAssetPath(value, label) {
if (typeof value !== "string" || value.length === 0 || value.length > MAX_PATH) {
fail(`${label} must be a non-empty relative path`);
return false;
}
if (value.includes("\0") || value.includes("\\") || isAbsolute(value) || /^[A-Za-z]:/.test(value)) {
fail(`${label} must use a workspace-relative POSIX path`);
return false;
}
const resolved = resolve(ROOT, value);
const fromRoot = relative(ROOT, resolved);
if (fromRoot.startsWith(`..${sep}`) || isAbsolute(fromRoot)) {
fail(`${label} escapes the workspace root: ${value}`);
return false;
}
return true;
}
function existingAssetPath(value, label) {
if (!confinedAssetPath(value, label)) return false;
const file = resolve(ROOT, value);
let stats;
try {
stats = lstatSync(file);
} catch {
fail(`${label} is not a file: ${value}`);
return false;
}
if (stats.isSymbolicLink()) {
fail(`${label} must not be a symbolic link: ${value}`);
return false;
}
if (!stats.isFile()) {
fail(`${label} is not a file: ${value}`);
return false;
}
return true;
}
function readJson(file, label) {
try {
const value = JSON.parse(readFileSync(file, "utf8"));
if (!value || typeof value !== "object" || Array.isArray(value)) {
fail(`${label} must contain one JSON object`);
return null;
}
return value;
} catch (error) {
fail(`${label} is not valid JSON (${error.constructor.name})`);
return null;
}
}
function boundedString(value, label, { allowEmpty = false } = {}) {
if (
typeof value !== "string" ||
value.length > MAX_TEXT ||
(!allowEmpty && value.trim().length === 0)
) {
fail(`${label} must be ${allowEmpty ? "a" : "a non-empty"} string up to ${MAX_TEXT} characters`);
return false;
}
return true;
}
function boundedArray(value, label) {
if (!Array.isArray(value) || value.length > MAX_ITEMS) {
fail(`${label} must be an array with at most ${MAX_ITEMS} items`);
return false;
}
return true;
}
function uniqueIds(items, label) {
const seen = new Set();
let valid = true;
for (const [index, item] of items.entries()) {
if (!item || typeof item !== "object" || Array.isArray(item)) {
fail(`${label}[${index}] must be an object`);
valid = false;
continue;
}
if (!boundedString(item.id, `${label}[${index}].id`)) {
valid = false;
continue;
}
if (seen.has(item.id)) {
fail(`${label} contains duplicate id ${JSON.stringify(item.id)}`);
valid = false;
}
seen.add(item.id);
}
return valid ? seen : null;
}
function positiveDimension(value, label, { integer = true } = {}) {
if (
typeof value !== "number" ||
!Number.isFinite(value) ||
value <= 0 ||
value > MAX_DIMENSION ||
(integer && !Number.isInteger(value))
) {
fail(`${label} must be a positive${integer ? " integer" : ""} <= ${MAX_DIMENSION}`);
return false;
}
return true;
}
function coordinate(value, label) {
if (typeof value !== "number" || !Number.isFinite(value) || value < 0 || value > MAX_DIMENSION) {
fail(`${label} must be a finite number from 0 to ${MAX_DIMENSION}`);
return false;
}
return true;
}
function validateOutput(output) {
if (!output || typeof output !== "object" || Array.isArray(output)) {
fail("output must be an object");
return;
}
positiveDimension(output.width, "output.width");
positiveDimension(output.height, "output.height");
boundedString(output.format, "output.format");
boundedString(output.mode, "output.mode");
}
// A revoked requirement stays in the ledger (it answers "why doesn't it do X any more?") and points
// at the requirement that replaced it. The chain must end on a live one, so a loop cannot retire all.
function validateSupersession(requirement, index, byId) {
let next = requirement.superseded_by;
if (typeof next !== "string" || next === requirement.id || !byId.has(next)) {
fail(`requirements[${index}] status=superseded needs superseded_by naming the requirement that replaced it`);
return;
}
const seen = new Set([requirement.id]);
while (byId.get(next)?.status === "superseded") {
if (seen.has(next)) {
fail(`requirements[${index}] superseded_by loops; the chain must end on a live requirement`);
return;
}
seen.add(next);
next = byId.get(next).superseded_by;
}
}
function validateContract(contract, phase) {
if (contract.version !== 1) fail("contract.version must be 1");
if (!new Set(["net-new", "reference-transform", "motion"]).has(contract.job_kind)) {
fail("job_kind must be net-new, reference-transform, or motion");
}
validateOutput(contract.output);
const source = contract.source;
if (!source || typeof source !== "object" || Array.isArray(source)) {
fail("source must be an object");
} else {
if (!new Set(["none", "reference", "copy", "reference-and-copy"]).has(source.kind)) {
fail("source.kind must be none, reference, copy, or reference-and-copy");
}
if (boundedArray(source.inventory, "source.inventory")) {
const ids = uniqueIds(source.inventory, "source.inventory");
for (const [index, item] of source.inventory.entries()) {
if (!item || typeof item !== "object" || Array.isArray(item)) continue;
boundedString(item.type, `source.inventory[${index}].type`);
boundedString(item.value, `source.inventory[${index}].value`);
}
if (source.kind !== "none" && ids?.size === 0) {
fail("reference/copy work requires a non-empty source.inventory");
}
}
for (const key of ["allowed_additions", "allowed_removals", "allowed_changes"]) {
if (!boundedArray(source[key], `source.${key}`)) continue;
source[key].forEach((item, index) => boundedString(item, `source.${key}[${index}]`));
}
}
if (boundedArray(contract.requirements, "requirements")) {
if (contract.requirements.length === 0) {
fail("requirements must include at least one explicit request");
}
uniqueIds(contract.requirements, "requirements");
const byId = new Map(contract.requirements.filter((item) => item?.id).map((item) => [item.id, item]));
for (const [index, requirement] of contract.requirements.entries()) {
if (!requirement || typeof requirement !== "object" || Array.isArray(requirement)) continue;
boundedString(requirement.request, `requirements[${index}].request`);
if (!new Set(["pending", "satisfied", "blocked", "superseded"]).has(requirement.status)) {
fail(`requirements[${index}].status must be pending, satisfied, blocked, or superseded`);
}
boundedString(requirement.evidence, `requirements[${index}].evidence`, { allowEmpty: true });
if (
new Set(["satisfied", "blocked", "superseded"]).has(requirement.status) &&
(!requirement.evidence || requirement.evidence.trim().length === 0)
) {
fail(`requirements[${index}] needs evidence when status=${requirement.status}`);
}
if (requirement.status === "superseded") validateSupersession(requirement, index, byId);
// Only the person can accept a blocked requirement; `waiver` records their words.
const waiver = requirement.waiver ?? "";
boundedString(waiver, `requirements[${index}].waiver`, { allowEmpty: true });
const waived = requirement.status === "blocked" && typeof waiver === "string" && waiver.trim();
if (phase === "final" && !["satisfied", "superseded"].includes(requirement.status) && !waived) {
fail(
`final validation requires ${requirement.id || `requirements[${index}]`} to be satisfied, ` +
"superseded by its replacement, or blocked with the person's waiver",
);
}
}
}
if (boundedArray(contract.assets, "assets")) {
uniqueIds(contract.assets, "assets");
for (const [index, asset] of contract.assets.entries()) {
if (!asset || typeof asset !== "object" || Array.isArray(asset)) continue;
boundedString(asset.role, `assets[${index}].role`);
if (typeof asset.required !== "boolean") fail(`assets[${index}].required must be boolean`);
if (asset.required === true) existingAssetPath(asset.path, `assets[${index}].path`);
else confinedAssetPath(asset.path, `assets[${index}].path`);
}
}
}
function validateRect(rect, label, canvas) {
if (!rect || typeof rect !== "object" || Array.isArray(rect)) {
fail(`${label} must be an object`);
return false;
}
let valid =
coordinate(rect.x, `${label}.x`) &&
coordinate(rect.y, `${label}.y`) &&
positiveDimension(rect.width, `${label}.width`, { integer: false }) &&
positiveDimension(rect.height, `${label}.height`, { integer: false });
if (valid && (rect.x + rect.width > canvas.width || rect.y + rect.height > canvas.height)) {
fail(`${label} must fit inside the canvas`);
valid = false;
}
return valid;
}
function contains(outer, inner) {
return (
inner.x >= outer.x &&
inner.y >= outer.y &&
inner.x + inner.width <= outer.x + outer.width &&
inner.y + inner.height <= outer.y + outer.height
);
}
function validateLayers(manifest) {
if (manifest.version !== 1) fail("layer manifest version must be 1");
const canvas = manifest.canvas;
if (!canvas || typeof canvas !== "object" || Array.isArray(canvas)) {
fail("canvas must be an object");
return;
}
positiveDimension(canvas.width, "canvas.width");
positiveDimension(canvas.height, "canvas.height");
const layerMap = new Map();
if (boundedArray(manifest.layers, "layers")) {
uniqueIds(manifest.layers, "layers");
for (const [index, layer] of manifest.layers.entries()) {
if (!layer || typeof layer !== "object" || Array.isArray(layer)) continue;
existingAssetPath(layer.path, `layers[${index}].path`);
boundedString(layer.role, `layers[${index}].role`);
if (!new Set(["separate-alpha", "vector", "flat-reference"]).has(layer.isolation)) {
fail(`layers[${index}].isolation must be separate-alpha, vector, or flat-reference`);
}
const boundsValid = validateRect(layer.bounds, `layers[${index}].bounds`, canvas);
if (
!layer.anchor ||
typeof layer.anchor !== "object" ||
!Number.isFinite(layer.anchor.x) ||
!Number.isFinite(layer.anchor.y) ||
layer.anchor.x < 0 ||
layer.anchor.x > 1 ||
layer.anchor.y < 0 ||
layer.anchor.y > 1
) {
fail(`layers[${index}].anchor must contain normalized x/y values from 0 to 1`);
}
if (boundedArray(layer.animate, `layers[${index}].animate`)) {
layer.animate.forEach((item, itemIndex) =>
boundedString(item, `layers[${index}].animate[${itemIndex}]`),
);
if (layer.animate.length > 0 && layer.isolation === "flat-reference") {
fail(`layers[${index}] cannot animate a flat-reference; request a separated alpha/vector layer`);
}
}
if (boundsValid && typeof layer.id === "string") layerMap.set(layer.id, layer);
}
}
if (boundedArray(manifest.safe_areas, "safe_areas")) {
uniqueIds(manifest.safe_areas, "safe_areas");
for (const [index, safeArea] of manifest.safe_areas.entries()) {
if (!safeArea || typeof safeArea !== "object" || Array.isArray(safeArea)) continue;
const validRect = validateRect(safeArea.bounds, `safe_areas[${index}].bounds`, canvas);
if (!boundedArray(safeArea.contains, `safe_areas[${index}].contains`)) continue;
for (const layerId of safeArea.contains) {
boundedString(layerId, `safe_areas[${index}].contains[]`);
const layer = layerMap.get(layerId);
if (!layer) fail(`safe_areas[${index}] references unknown layer ${JSON.stringify(layerId)}`);
else if (validRect && !contains(safeArea.bounds, layer.bounds)) {
fail(`layer ${JSON.stringify(layerId)} does not fit safe area ${JSON.stringify(safeArea.id)}`);
}
}
}
}
if (boundedArray(manifest.attachments, "attachments")) {
for (const [index, attachment] of manifest.attachments.entries()) {
if (!attachment || typeof attachment !== "object" || Array.isArray(attachment)) {
fail(`attachments[${index}] must be an object`);
continue;
}
for (const key of ["child", "parent", "child_anchor", "parent_anchor"]) {
boundedString(attachment[key], `attachments[${index}].${key}`);
}
if (!layerMap.has(attachment.child)) {
fail(`attachments[${index}] references unknown child ${JSON.stringify(attachment.child)}`);
}
if (!layerMap.has(attachment.parent)) {
fail(`attachments[${index}] references unknown parent ${JSON.stringify(attachment.parent)}`);
}
if (attachment.child === attachment.parent) fail(`attachments[${index}] cannot self-attach`);
}
}
}
// --- measuring produced files ----------------------------------------------------------------------
// Stills are read from their own header bytes: a truncated or mislabelled file fails here without an
// image library. Each reader returns {format, width, height} or a problem string.
function readPng(buf) {
if (buf.length < 33 || buf.readUInt32BE(0) !== 0x89504e47 || buf.readUInt32BE(4) !== 0x0d0a1a0a) return "not a PNG (bad signature)";
if (buf.toString("latin1", 12, 16) !== "IHDR") return "not a PNG (no IHDR chunk)";
let off = 8;
let idat = false;
while (off + 12 <= buf.length) {
const len = buf.readUInt32BE(off);
const type = buf.toString("latin1", off + 4, off + 8);
if (off + 12 + len > buf.length) return `truncated PNG (${type} chunk runs past the end of the file)`;
if (type === "IDAT") idat = true;
if (type === "IEND") {
if (!idat) return "PNG has no image data (no IDAT chunk)";
return { format: "png", width: buf.readUInt32BE(16), height: buf.readUInt32BE(20) };
}
off += 12 + len;
}
return "truncated PNG (no IEND chunk)";
}
// Start-of-frame markers carry the dimensions; C4 (DHT), C8 (JPG) and CC (DAC) are not frames.
const JPEG_SOF = new Set([0xc0, 0xc1, 0xc2, 0xc3, 0xc5, 0xc6, 0xc7, 0xc9, 0xca, 0xcb, 0xcd, 0xce, 0xcf]);
function readJpeg(buf) {
if (buf.length < 4 || buf[0] !== 0xff || buf[1] !== 0xd8) return "not a JPEG (no SOI marker)";
let size = null;
let off = 2;
while (off + 4 <= buf.length) {
if (buf[off] !== 0xff) return "corrupt JPEG (segment does not start with 0xFF)";
const marker = buf[off + 1];
if (marker === 0xff) { off++; continue; } // fill byte
if (marker === 0xd9) break;
if (marker === 0x01 || (marker >= 0xd0 && marker <= 0xd7)) { off += 2; continue; }
const len = buf.readUInt16BE(off + 2);
if (len < 2 || off + 2 + len > buf.length) return "truncated JPEG (segment runs past the end of the file)";
if (JPEG_SOF.has(marker) && len >= 7) size = { width: buf.readUInt16BE(off + 7), height: buf.readUInt16BE(off + 5) };
if (marker === 0xda) break; // entropy-coded data follows; the end marker is checked below
off += 2 + len;
}
if (!size) return "corrupt JPEG (no start-of-frame segment)";
if (buf[buf.length - 2] !== 0xff || buf[buf.length - 1] !== 0xd9) return "truncated JPEG (no EOI marker)";
return { format: "jpeg", ...size };
}
function readWebp(buf) {
if (buf.length < 30 || buf.toString("latin1", 0, 4) !== "RIFF" || buf.toString("latin1", 8, 12) !== "WEBP") return "not a WebP (bad RIFF header)";
if (buf.readUInt32LE(4) + 8 > buf.length) return "truncated WebP (RIFF size runs past the end of the file)";
const chunk = buf.toString("latin1", 12, 16);
if (chunk === "VP8X") return { format: "webp", width: 1 + buf.readUIntLE(24, 3), height: 1 + buf.readUIntLE(27, 3) };
if (chunk === "VP8L") {
if (buf[20] !== 0x2f) return "corrupt WebP (bad lossless signature)";
const bits = buf.readUInt32LE(21);
return { format: "webp", width: 1 + (bits & 0x3fff), height: 1 + ((bits >> 14) & 0x3fff) };
}
if (chunk === "VP8 ") {
if (buf[23] !== 0x9d || buf[24] !== 0x01 || buf[25] !== 0x2a) return "corrupt WebP (bad lossy start code)";
return { format: "webp", width: buf.readUInt16LE(26) & 0x3fff, height: buf.readUInt16LE(28) & 0x3fff };
}
return `not a WebP image (first chunk ${JSON.stringify(chunk)})`;
}
const STILL_READERS = { ".png": readPng, ".jpg": readJpeg, ".jpeg": readJpeg, ".webp": readWebp };
const VIDEO_EXTENSIONS = new Set([".mp4", ".mov", ".webm", ".m4v"]);
function run(binary, args, { encoding = "utf8", maxBuffer = 64 * 1024 * 1024 } = {}) {
const result = spawnSync(binary, args, { encoding, maxBuffer });
if (result.error?.code === "ENOENT") throw new ToolingError(`${binary} is not installed (run inside the sandbox image)`);
if (result.error) throw new ToolingError(`${binary} failed: ${result.error.message}`);
return result;
}
// Non-ground pixels against the frame's own modal color: mean luminance hides a frame whose only
// content is one headline. Floor: ~3000 px on a 1920x1080 frame, kept as a fraction of the frame.
const INK_DISTANCE = 36;
export const BLANK_INK = 3000 / (1920 * 1080);
const SAMPLE_W = 192;
const SAMPLE_H = 108;
export function inkFraction(rgb) {
const counts = new Map();
for (let i = 0; i + 2 < rgb.length; i += 3) {
const key = ((rgb[i] >> 3) << 10) | ((rgb[i + 1] >> 3) << 5) | (rgb[i + 2] >> 3);
counts.set(key, (counts.get(key) || 0) + 1);
}
let modal = 0;
let modalKey = 0;
for (const [key, count] of counts) if (count > modal) { modal = count; modalKey = key; }
const r = ((modalKey >> 10) & 31) * 8 + 4, g = ((modalKey >> 5) & 31) * 8 + 4, b = (modalKey & 31) * 8 + 4;
let ink = 0;
for (let i = 0; i + 2 < rgb.length; i += 3) {
if (Math.abs(rgb[i] - r) + Math.abs(rgb[i + 1] - g) + Math.abs(rgb[i + 2] - b) > INK_DISTANCE) ink++;
}
return ink / (rgb.length / 3);
}
function frameInk(file, which) {
const frameBytes = SAMPLE_W * SAMPLE_H * 3;
const seek = which === "last" ? ["-sseof", "-1"] : [];
const out = run(
"ffmpeg",
["-v", "error", "-nostdin", ...seek, "-i", file, ...(which === "first" ? ["-frames:v", "1"] : []),
"-vf", `scale=${SAMPLE_W}:${SAMPLE_H}:flags=area`, "-f", "rawvideo", "-pix_fmt", "rgb24", "pipe:1"],
{ encoding: "buffer", maxBuffer: 512 * 1024 * 1024 },
);
if (out.status !== 0 || out.stdout.length < frameBytes) return null;
const start = which === "last" ? out.stdout.length - frameBytes : 0;
return inkFraction(out.stdout.subarray(start, start + frameBytes));
}
function measureVideo(file) {
const probe = run("ffprobe", [
"-v", "error", "-select_streams", "v:0",
"-show_entries", "stream=codec_name,width,height,avg_frame_rate:format=duration,format_name",
"-of", "json", file,
]);
if (probe.status !== 0) return `not a decodable video (${(probe.stderr || "").trim().split("\n")[0] || "ffprobe failed"})`;
const info = JSON.parse(probe.stdout || "{}");
const stream = info.streams?.[0];
if (!stream) return "has no video stream";
const [num, den] = String(stream.avg_frame_rate || "0/1").split("/").map(Number);
return {
format: info.format?.format_name || "video",
codec: stream.codec_name,
width: stream.width,
height: stream.height,
duration: Number(info.format?.duration),
fps: den ? num / den : null,
firstFrameInk: frameInk(file, "first"),
lastFrameInk: frameInk(file, "last"),
};
}
/** `out/a.png:1080x1350` or `out/film.mp4:1920x1080@2` (the path may itself contain colons). */
export function parseExpectation(spec) {
const m = /^(.+):(\d{1,5})x(\d{1,5})(?:@(\d+(?:\.\d+)?)s?)?$/.exec(spec);
if (!m) throw new ToolingError(`--expect must look like <path>:<W>x<H> or <path>:<W>x<H>@<seconds>, got "${spec}"`);
return { path: m[1], width: Number(m[2]), height: Number(m[3]), duration: m[4] === undefined ? null : Number(m[4]) };
}
/** Measure one produced file against what was asked for. Returns the report entry with `problems`. */
export function checkOutput(expected, { allowBlankEnds = false } = {}) {
const entry = { path: expected.path, expected: { width: expected.width, height: expected.height }, problems: [] };
if (expected.duration !== null && expected.duration !== undefined) entry.expected.duration = expected.duration;
const file = resolve(ROOT, expected.path);
const fromRoot = relative(ROOT, file);
if (fromRoot.startsWith(`..${sep}`) || isAbsolute(fromRoot)) throw new ToolingError(`${expected.path} escapes the workspace root ${ROOT}`);
let stats;
try {
stats = statSync(file);
} catch {
entry.problems.push("does not exist");
return entry;
}
if (!stats.isFile()) {
entry.problems.push("is not a file");
return entry;
}
entry.bytes = stats.size;
if (stats.size === 0) {
entry.problems.push("is empty (0 bytes)");
return entry;
}
const ext = extname(file).toLowerCase();
let measured;
if (STILL_READERS[ext]) {
measured = STILL_READERS[ext](readFileSync(file));
if (expected.duration !== null && expected.duration !== undefined) entry.problems.push(`a duration was expected but ${ext} is a still`);
} else if (VIDEO_EXTENSIONS.has(ext)) {
measured = measureVideo(file);
} else {
entry.problems.push(`unsupported output type ${ext || "(no extension)"}: expected .png, .jpg, .webp, .mp4, .mov or .webm`);
return entry;
}
if (typeof measured === "string") {
entry.problems.push(measured);
return entry;
}
Object.assign(entry, measured);
if (measured.width !== expected.width || measured.height !== expected.height) {
entry.problems.push(`is ${measured.width}x${measured.height}, expected ${expected.width}x${expected.height}`);
}
if (VIDEO_EXTENSIONS.has(ext)) {
if (expected.duration !== null && expected.duration !== undefined) {
const frame = measured.fps > 0 ? 1 / measured.fps : 1 / 30;
if (!(Math.abs(measured.duration - expected.duration) <= frame + 1e-6)) {
entry.problems.push(`runs ${measured.duration}s, expected ${expected.duration}s (within one frame, ${frame.toFixed(4)}s)`);
}
}
for (const which of ["first", "last"]) {
const ink = measured[`${which}FrameInk`];
if (ink === null) entry.problems.push(`its ${which} frame could not be decoded`);
else if (ink < BLANK_INK && !allowBlankEnds) entry.problems.push(`its ${which} frame is blank (ink ${ink.toFixed(5)} < ${BLANK_INK.toFixed(5)} of the frame)`);
}
}
return entry;
}
if (isMain(import.meta.url)) {
await runCli("artifact-contract", async () => {
const { flags, positionals } = parseFlags(process.argv.slice(2), {
values: ["contract", "layers", "phase", "root"],
multi: ["expect"],
booleans: ["json", "allow-blank-ends"],
});
if (positionals.length) throw new ToolingError(`unexpected argument ${positionals[0]}`);
ROOT = resolve(flags.root || WORKSPACE);
const phase = flags.phase || "plan";
if (!new Set(["plan", "final"]).has(phase)) throw new ToolingError("--phase must be plan or final");
if (!flags.contract && !flags.layers && !flags.expect.length) {
throw new ToolingError("provide --contract, --layers and/or --expect <path>:<W>x<H>");
}
const options = { allowBlankEnds: Boolean(flags["allow-blank-ends"]) };
const outputs = [];
for (const expectation of flags.expect.map(parseExpectation)) outputs.push(checkOutput(expectation, options));
if (flags.contract) {
const contract = readJson(confinedFile(flags.contract, "--contract"), "contract");
if (contract) {
validateContract(contract, phase);
const out = contract.output;
if (phase === "final" && out && typeof out === "object" && typeof out.path === "string") {
if (confinedAssetPath(out.path, "output.path")) {
outputs.push(
checkOutput(
{ path: out.path, width: out.width, height: out.height, duration: out.duration_s ?? null },
{ allowBlankEnds: options.allowBlankEnds || out.allow_blank_ends === true },
),
);
}
}
}
}
if (flags.layers) {
const manifest = readJson(confinedFile(flags.layers, "--layers"), "layer manifest");
if (manifest) validateLayers(manifest);
}
for (const entry of outputs) for (const problem of entry.problems) fail(`${entry.path} ${problem}`);
const ok = problems.length === 0;
if (flags.json) {
console.log(JSON.stringify({ ok, phase: flags.contract ? phase : undefined, outputs, problems }));
} else {
for (const problem of problems) console.error(`artifact-contract: ${problem}`);
for (const entry of outputs.filter((e) => !e.problems.length)) {
console.log(` ok ${entry.path} ${entry.width}x${entry.height}${entry.duration ? ` ${entry.duration}s` : ""} ${entry.bytes} bytes`);
}
if (ok) console.log(`__ARTIFACT_CONTRACT_OK__${flags.contract ? ` phase=${phase}` : ""}`);
}
return ok ? EXIT.PASS : EXIT.FINDINGS;
});
}