@prestyj/cli 5.27.0 → 5.28.1

package/assets/motion/bin/motion-check.mjs

@@ -0,0 +1,256 @@
+#!/usr/bin/env node
+// Check decoded video pixels, not DOM geometry: works for HTML, canvas and WebGL.
+// A freeze detector is not a creative-quality score. Review choreography too.
+import { execFile } from "node:child_process";
+import { open, stat } from "node:fs/promises";
+import { createReadStream } from "node:fs";
+import { createHash } from "node:crypto";
+import { resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { promisify } from "node:util";
+import { ffmpegBinary } from "./media-binaries.mjs";
+
+const run = promisify(execFile);
+
+/** Parse only completed FFmpeg progress + freezedetect metadata; never infer a pass from silence. */
+export function parseMotionOutput(text, slideshowRequested = false, holds = []) {
+  const invalid = () => ({
+    ok: false,
+    error: "Incomplete or malformed pixel analysis; motion is unverified",
+  });
+  if (typeof text !== "string" || typeof slideshowRequested !== "boolean") return invalid();
+  let samples = 0;
+  let duration = 0;
+  let complete = false;
+  let start = null;
+  const freezes = [];
+  for (const line of text.split(/\r?\n/)) {
+    const equals = line.indexOf("=");
+    if (equals < 0) continue;
+    const key = line.slice(0, equals).trim();
+    const value = line.slice(equals + 1).trim();
+    if (key === "progress") {
+      complete = value === "end";
+      continue;
+    }
+    if (
+      ![
+        "frame",
+        "out_time_us",
+        "lavfi.freezedetect.freeze_start",
+        "lavfi.freezedetect.freeze_end",
+        "lavfi.freezedetect.freeze_duration",
+      ].includes(key)
+    )
+      continue;
+    const number = Number(value);
+    if (!value || !Number.isFinite(number) || number < 0) return invalid();
+    if (key === "frame") {
+      if (!Number.isInteger(number) || number < samples) return invalid();
+      samples = number;
+    } else if (key === "out_time_us") {
+      if (number / 1e6 < duration) return invalid();
+      duration = number / 1e6;
+    } else if (key === "lavfi.freezedetect.freeze_start") {
+      if (start !== null) return invalid();
+      start = number;
+    } else if (key === "lavfi.freezedetect.freeze_duration") {
+      if (start === null || number < 1) return invalid();
+    } else if (key === "lavfi.freezedetect.freeze_end") {
+      if (start === null || number < start) return invalid();
+      freezes.push({ start, end: number, duration: number - start });
+      start = null;
+    }
+  }
+  if (!complete || samples < 2 || duration <= 0 || Math.abs(samples / 8 - duration) > 0.25)
+    return invalid();
+  if (start !== null) freezes.push({ start, end: duration, duration: duration - start });
+  if (freezes.some((freeze) => freeze.duration < 1 || freeze.end > duration + 0.125))
+    return invalid();
+  // Hold declarations are narrow exceptions, never a substitute for decoding.
+  // One sample of tolerance accounts for the fixed 8fps analysis grid.
+  const tolerance = 1 / 8;
+  let previousEnd = 0;
+  let heldDuration = 0;
+  if (!Array.isArray(holds) || holds.length > 128 || (slideshowRequested && holds.length))
+    return { ok: false, error: "Invalid hold declarations" };
+  for (const hold of holds) {
+    if (
+      !hold ||
+      typeof hold !== "object" ||
+      Array.isArray(hold) ||
+      Object.keys(hold).some((key) => !["start", "end", "reason"].includes(key)) ||
+      !Number.isFinite(hold.start) ||
+      !Number.isFinite(hold.end) ||
+      hold.start < previousEnd ||
+      hold.end <= hold.start ||
+      hold.end > duration ||
+      typeof hold.reason !== "string" ||
+      !hold.reason.trim() ||
+      hold.reason.length > 500
+    )
+      return {
+        ok: false,
+        error: "Holds need ordered, non-overlapping in-range times and a reason",
+      };
+    previousEnd = hold.end;
+    heldDuration += hold.end - hold.start;
+  }
+  if (heldDuration >= duration - tolerance)
+    return {
+      ok: false,
+      error:
+        "Holds cannot exempt the entire video; explicitly requested slideshows use their own mode",
+    };
+  const staleHolds = holds.filter(
+    (hold) => !freezes.some((freeze) => freeze.end > hold.start && freeze.start < hold.end),
+  );
+  // Name the stale holds and where pixels actually freeze, so the plan is fixed in one
+  // step instead of guessed again against another full check.
+  if (staleHolds.length)
+    return {
+      ok: false,
+      error: "Stale hold declaration: no detected freeze overlaps its window",
+      staleHolds,
+      freezes,
+    };
+  const unexpectedFreezes = freezes.filter(
+    (freeze) =>
+      !holds.some(
+        (hold) => freeze.start >= hold.start - tolerance && freeze.end <= hold.end + tolerance,
+      ),
+  );
+  return {
+    ok: slideshowRequested || unexpectedFreezes.length === 0,
+    method: "rendered-pixels",
+    samples,
+    duration,
+    freezes,
+    holds,
+    unexpectedFreezes,
+    slideshowRequested,
+    visualReviewRequired: true,
+  };
+}
+
+async function videoHash(file, signal) {
+  const hash = createHash("sha256");
+  for await (const chunk of createReadStream(file, { signal })) hash.update(chunk);
+  return hash.digest("hex");
+}
+
+async function readHoldPlan(file, signal) {
+  // Bound reads even if a local file grows between stat and read.
+  const handle = await open(file, "r");
+  try {
+    signal.throwIfAborted();
+    if (!(await handle.stat()).isFile()) throw new Error("Expected a local hold-plan file");
+    const bytes = Buffer.alloc(64 * 1024 + 1);
+    let size = 0;
+    while (size < bytes.length) {
+      signal.throwIfAborted();
+      const { bytesRead } = await handle.read(bytes, size, bytes.length - size, null);
+      if (!bytesRead) break;
+      size += bytesRead;
+    }
+    if (size === bytes.length) throw new Error("Hold plan exceeds 64 KiB");
+    const plan = JSON.parse(bytes.subarray(0, size).toString("utf8"));
+    if (
+      !plan ||
+      typeof plan !== "object" ||
+      Array.isArray(plan) ||
+      plan.version !== 1 ||
+      Object.keys(plan).some((key) => !["version", "videoSha256", "holds"].includes(key)) ||
+      typeof plan.videoSha256 !== "string" ||
+      !/^[a-f0-9]{64}$/.test(plan.videoSha256) ||
+      !Array.isArray(plan.holds) ||
+      !plan.holds.length
+    )
+      throw new Error("Expected hold plan version 1 with videoSha256 and nonempty holds");
+    return plan;
+  } finally {
+    await handle.close();
+  }
+}
+
+async function main() {
+  const [video, option, holdFile, ...extra] = process.argv.slice(2);
+  if (
+    !video ||
+    extra.length ||
+    (option === "--holds" ? !holdFile : holdFile || (option && option !== "--slideshow-requested"))
+  ) {
+    throw new Error(
+      "usage: motion-check.mjs <rendered-video> [--holds <holds.json> | --slideshow-requested]",
+    );
+  }
+  const file = resolve(video);
+  if (!(await stat(file)).isFile()) throw new Error("Expected a local rendered video file");
+  const binary = await ffmpegBinary();
+  const controller = new AbortController();
+  const abort = () => controller.abort();
+  process.once("SIGTERM", abort);
+  process.once("SIGINT", abort);
+  const started = performance.now();
+  try {
+    const plan = holdFile ? await readHoldPlan(resolve(holdFile), controller.signal) : null;
+    const videoSha256 = await videoHash(file, controller.signal);
+    if (plan && plan.videoSha256 !== videoSha256)
+      throw new Error(
+        "Hold plan belongs to a different render; review this file before updating it",
+      );
+    const { stdout } = await run(
+      binary,
+      [
+        "-hide_banner",
+        "-nostdin",
+        "-loglevel",
+        "error",
+        "-xerror",
+        "-protocol_whitelist",
+        "file,pipe",
+        "-i",
+        file,
+        "-map",
+        "0:v:0",
+        "-an",
+        "-vf",
+        "fps=8,scale=320:180,freezedetect=n=0.001:d=1,metadata=mode=print:file=-",
+        "-progress",
+        "pipe:1",
+        "-nostats",
+        "-f",
+        "null",
+        "-",
+      ],
+      {
+        encoding: "utf8",
+        timeout: 180_000,
+        maxBuffer: 2 * 1024 * 1024,
+        windowsHide: true,
+        signal: controller.signal,
+      },
+    );
+    if ((await videoHash(file, controller.signal)) !== videoSha256)
+      throw new Error("Video changed during analysis; motion is unverified");
+    const result = parseMotionOutput(stdout, option === "--slideshow-requested", plan?.holds ?? []);
+    process.stdout.write(
+      `${JSON.stringify({ ...result, file, videoSha256, elapsedMs: Math.round(performance.now() - started) })}\n`,
+    );
+    if (!result.ok) process.exitCode = 1;
+  } finally {
+    process.removeListener("SIGTERM", abort);
+    process.removeListener("SIGINT", abort);
+  }
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1])).href) {
+  try {
+    await main();
+  } catch (error) {
+    process.stderr.write(
+      `Motion verification failed: ${error instanceof Error ? error.message : "invalid input"}\n`,
+    );
+    process.exitCode = 1;
+  }
+}

package/assets/motion/bin/pdf-extract.mjs

@@ -0,0 +1,133 @@
+#!/usr/bin/env node
+// EZ Motion PDF ingest: text per page, metadata, and embedded images, using the
+// `unpdf` package EZ already ships. No network, no extra installs.
+//
+// Usage: node pdf-extract.mjs <input.pdf> <output-dir>
+// Writes: <out>/text.md (page-delimited text), <out>/meta.json,
+//         <out>/images/p<page>-<n>.png (embedded raster images, when present)
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { basename, join, resolve } from "node:path";
+import { deflateSync } from "node:zlib";
+
+const [inputArg, outArg] = process.argv.slice(2);
+if (!inputArg || !outArg) {
+  process.stderr.write("usage: pdf-extract.mjs <input.pdf> <output-dir>\n");
+  process.exit(2);
+}
+
+let unpdf;
+try {
+  unpdf = await import("unpdf");
+} catch {
+  process.stderr.write("PDF support is missing from this EZ install (unpdf not found).\n");
+  process.exit(1);
+}
+
+/** Minimal PNG encoder for RGBA/RGB/gray pixel buffers (no native deps). */
+function encodePng(width, height, channels, pixels) {
+  const colorType = channels === 4 ? 6 : channels === 3 ? 2 : 0;
+  const stride = width * channels;
+  const raw = Buffer.alloc((stride + 1) * height);
+  for (let y = 0; y < height; y++) {
+    raw[y * (stride + 1)] = 0;
+    Buffer.from(pixels.buffer, pixels.byteOffset + y * stride, stride).copy(raw, y * (stride + 1) + 1);
+  }
+  const crcTable = new Int32Array(256).map((_, n) => {
+    let c = n;
+    for (let k = 0; k < 8; k++) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+    return c;
+  });
+  const crc = (buf) => {
+    let c = -1;
+    for (const b of buf) c = crcTable[(c ^ b) & 0xff] ^ (c >>> 8);
+    return (c ^ -1) >>> 0;
+  };
+  const chunk = (type, data) => {
+    const len = Buffer.alloc(4);
+    len.writeUInt32BE(data.length);
+    const td = Buffer.concat([Buffer.from(type, "ascii"), data]);
+    const sum = Buffer.alloc(4);
+    sum.writeUInt32BE(crc(td));
+    return Buffer.concat([len, td, sum]);
+  };
+  const ihdr = Buffer.alloc(13);
+  ihdr.writeUInt32BE(width, 0);
+  ihdr.writeUInt32BE(height, 4);
+  ihdr[8] = 8;
+  ihdr[9] = colorType;
+  return Buffer.concat([
+    Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]),
+    chunk("IHDR", ihdr),
+    chunk("IDAT", deflateSync(raw)),
+    chunk("IEND", Buffer.alloc(0)),
+  ]);
+}
+
+const input = resolve(inputArg);
+const outDir = resolve(outArg);
+await mkdir(join(outDir, "images"), { recursive: true });
+
+let pdf;
+let totalPages;
+let text;
+try {
+  const bytes = new Uint8Array(await readFile(input));
+  pdf = await unpdf.getDocumentProxy(bytes);
+  ({ totalPages, text } = await unpdf.extractText(pdf, { mergePages: false }));
+} catch (error) {
+  // pdf.js errors carry the whole minified bundle in their stack; keep only the message.
+  const message = error instanceof Error || (error && typeof error.message === "string")
+    ? error.message
+    : String(error);
+  process.stderr.write(`Could not read PDF ${input}: ${message}\n`);
+  process.exit(1);
+}
+
+let info = {};
+try {
+  info = (await unpdf.getMeta(pdf)).info ?? {};
+} catch {
+  // Metadata is optional.
+}
+
+const pages = Array.isArray(text) ? text : [String(text)];
+const md = [`# ${basename(input)}`, ""];
+pages.forEach((pageText, i) => {
+  md.push(`## Page ${i + 1}`, "", pageText.trim() || "_(no extractable text — likely scanned or image-only)_", "");
+});
+await writeFile(join(outDir, "text.md"), md.join("\n"));
+
+const images = [];
+const MIN_EDGE = 120; // skip icons, bullets and rules
+for (let page = 1; page <= totalPages; page++) {
+  let extracted = [];
+  try {
+    extracted = await unpdf.extractImages(pdf, page);
+  } catch {
+    continue;
+  }
+  let n = 0;
+  for (const img of extracted) {
+    if (!img?.data || img.width < MIN_EDGE || img.height < MIN_EDGE) continue;
+    const channels = img.channels ?? Math.round(img.data.length / (img.width * img.height));
+    if (![1, 3, 4].includes(channels)) continue;
+    n += 1;
+    const file = `p${page}-${n}.png`;
+    await writeFile(join(outDir, "images", file), encodePng(img.width, img.height, channels, img.data));
+    images.push({ page, file: `images/${file}`, width: img.width, height: img.height });
+  }
+}
+
+const emptyPages = pages
+  .map((t, i) => (t.trim() ? null : i + 1))
+  .filter((p) => p !== null);
+const meta = {
+  source: input,
+  pages: totalPages,
+  title: typeof info.Title === "string" ? info.Title : null,
+  author: typeof info.Author === "string" ? info.Author : null,
+  pagesWithoutText: emptyPages,
+  images,
+};
+await writeFile(join(outDir, "meta.json"), `${JSON.stringify(meta, null, 2)}\n`);
+process.stdout.write(`${JSON.stringify({ ok: true, pages: totalPages, images: images.length, pagesWithoutText: emptyPages.length, outDir })}\n`);

package/assets/motion/bin/reveal.mjs

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+// EZ Motion reveal: open the user's file manager at a finished video, with the
+// file selected where the OS supports it (Finder, Explorer). Linux file
+// managers have no common "select" flag, so the containing folder opens.
+//
+// Usage: node reveal.mjs <file-or-folder> [--dry-run] [--platform darwin|win32|linux]
+// --dry-run prints the command instead of running it; --platform only works
+// with --dry-run (for tests). Prints one JSON line: {"ok":true,"cmd":…,"args":…}.
+import { spawn } from "node:child_process";
+import { stat } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+
+function fail(message) {
+  process.stdout.write(`${JSON.stringify({ ok: false, error: message })}\n`);
+  process.exit(1);
+}
+
+const args = process.argv.slice(2);
+const dryRun = args.includes("--dry-run");
+const platformIndex = args.indexOf("--platform");
+const platformArg = platformIndex >= 0 ? args[platformIndex + 1] : undefined;
+const positional = args.filter(
+  (a, i) => !a.startsWith("--") && !(platformIndex >= 0 && i === platformIndex + 1),
+);
+const target = positional[0];
+if (!target || positional.length > 1) {
+  fail("usage: reveal.mjs <file-or-folder> [--dry-run] [--platform darwin|win32|linux]");
+}
+if (platformArg !== undefined && !dryRun) fail("--platform only works with --dry-run");
+if (platformArg !== undefined && !["darwin", "win32", "linux"].includes(platformArg)) {
+  fail("--platform must be darwin, win32 or linux");
+}
+const platform = platformArg ?? process.platform;
+
+const full = resolve(target);
+const info = await stat(full).catch(() => undefined);
+if (!info) fail(`Not found: ${full}`);
+const isDir = info.isDirectory();
+
+/** @returns {{ cmd: string, args: string[], verbatim: boolean }} */
+function revealCommand() {
+  if (platform === "darwin") {
+    return { cmd: "open", args: isDir ? [full] : ["-R", full], verbatim: false };
+  }
+  if (platform === "win32") {
+    // Explorer parses `/select,"<path>"` itself and rejects Node's default
+    // quoting of the whole argument, so pass it verbatim. Windows paths cannot
+    // contain `"`, so the quotes cannot be broken out of.
+    return {
+      cmd: "explorer.exe",
+      args: isDir ? [`"${full}"`] : [`/select,"${full}"`],
+      verbatim: true,
+    };
+  }
+  return { cmd: "xdg-open", args: [isDir ? full : dirname(full)], verbatim: false };
+}
+
+const command = revealCommand();
+if (!dryRun) {
+  await new Promise((resolveLaunch) => {
+    const child = spawn(command.cmd, command.args, {
+      detached: true,
+      stdio: "ignore",
+      windowsVerbatimArguments: command.verbatim,
+    });
+    // Explorer exits 1 even on success, so only a failed launch counts.
+    child.once("error", (error) => fail(`Could not open the file manager: ${error.message}`));
+    child.once("spawn", () => {
+      child.unref();
+      resolveLaunch(undefined);
+    });
+  });
+}
+process.stdout.write(
+  `${JSON.stringify({ ok: true, revealed: full, cmd: command.cmd, args: command.args, dryRun })}\n`,
+);