@prestyj/cli 5.27.0 → 5.28.0

package/assets/motion/assets/sfx/sfx-analysis.md

@@ -0,0 +1,75 @@
+# SFX Analysis Summary
+
+Source: [Nolanney](https://kenney.nl/).
+
+Use this as planning guidance for choosing tasteful SFX. Prefer low/medium high-frequency risk sounds for polished videos; reserve bright/high-risk files for tiny accents, chaotic tones, or deliberate glitches.
+
+## Signal Guide
+
+- `brightness`: warm / balanced / bright, based on spectral centroid and high-frequency energy.
+- `highFrequencyRisk`: low / medium / high. High-risk SFX can feel sharp, hissy, clicky, or fatiguing if repeated.
+- `brightBurden`: high-frequency energy weighted by level and duration. This separates sustained glassy ringing from short clicks.
+- `highActiveDuration`: how long bright energy stays active above a useful level.
+- `envelopeShape`: transient / textured / continuous. Continuous bright sounds are more fatiguing than sparse textured sounds.
+- `transient.sharpness`: higher values feel clickier or more percussive.
+- `duration`: short sounds work for UI and typing; longer sounds work for reveals and transitions.
+
+## Safest General Picks
+
+- `impact/impactSoft_medium_001.ogg` — 0.18s, warm, low HF risk, transient; use for hard transition, major reveal
+- `impact/impactSoft_medium_004.ogg` — 0.15s, warm, low HF risk, transient; use for hard transition, major reveal
+- `impact/impactSoft_medium_002.ogg` — 0.14s, warm, low HF risk, transient; use for hard transition, major reveal
+- `interface/bong_001.ogg` — 0.12s, warm, low HF risk, textured; use for general accent
+- `impact/impactSoft_medium_003.ogg` — 0.14s, warm, low HF risk, textured; use for hard transition, major reveal
+- `impact/impactSoft_medium_000.ogg` — 0.12s, warm, low HF risk, textured; use for hard transition, major reveal
+- `interface/click_003.ogg` — 0.01s, balanced, low HF risk, continuous; use for button press, selection, simulated user action
+- `interface/click_002.ogg` — 0.01s, balanced, low HF risk, continuous; use for button press, selection, simulated user action
+- `interface/click_005.ogg` — 0.01s, balanced, low HF risk, continuous; use for button press, selection, simulated user action
+- `ui/click2.ogg` — 0.06s, balanced, low HF risk, continuous; use for button press, selection, simulated user action
+- `ui/rollover2.ogg` — 0.06s, balanced, low HF risk, continuous; use for general accent
+- `interface/glitch_002.ogg` — 0.03s, bright, low HF risk, continuous; use for chaotic accent, comedic interruption, tiny accent only
+- `impact/impactSoft_heavy_003.ogg` — 0.54s, warm, medium HF risk, transient; use for hard transition, major reveal
+- `impact/impactSoft_heavy_004.ogg` — 0.50s, warm, medium HF risk, transient; use for hard transition, major reveal
+- `impact/impactSoft_heavy_002.ogg` — 0.57s, warm, medium HF risk, transient; use for hard transition, major reveal
+- `impact/impactSoft_heavy_001.ogg` — 0.57s, warm, medium HF risk, transient; use for hard transition, major reveal
+- `impact/impactSoft_heavy_000.ogg` — 0.51s, warm, medium HF risk, transient; use for hard transition, major reveal
+- `impact/footstep_wood_004.ogg` — 0.25s, warm, medium HF risk, transient; use for general accent
+- `impact/footstep_wood_002.ogg` — 0.25s, warm, medium HF risk, transient; use for general accent
+- `impact/footstep_wood_000.ogg` — 0.25s, warm, medium HF risk, transient; use for general accent
+- `impact/footstep_wood_001.ogg` — 0.25s, warm, medium HF risk, transient; use for general accent
+- `impact/impactWood_medium_003.ogg` — 0.33s, warm, medium HF risk, transient; use for hard transition, major reveal
+- `impact/impactWood_medium_001.ogg` — 0.33s, warm, medium HF risk, transient; use for hard transition, major reveal
+- `impact/impactWood_medium_000.ogg` — 0.33s, warm, medium HF risk, transient; use for hard transition, major reveal
+
+## Lower-Risk Picks By Use Case
+
+- button press: `interface/click_003.ogg` (low), `interface/click_002.ogg` (low), `interface/click_005.ogg` (low), `ui/click2.ogg` (low), `interface/click_001.ogg` (medium)
+- selection: `interface/click_003.ogg` (low), `interface/click_002.ogg` (low), `interface/click_005.ogg` (low), `ui/click2.ogg` (low), `interface/click_001.ogg` (medium)
+- toggle: `interface/switch_007.ogg` (medium), `interface/switch_002.ogg` (medium), `interface/switch_006.ogg` (medium), `interface/switch_005.ogg` (medium), `ui/switch11.ogg` (medium)
+- card reveal: `casino/card-slide-1.ogg` (medium), `casino/card-place-1.ogg` (high), `casino/card-fan-2.ogg` (high), `casino/card-slide-8.ogg` (high), `casino/card-slide-3.ogg` (high)
+- swipe: `casino/card-slide-1.ogg` (medium), `casino/card-place-1.ogg` (high), `casino/card-fan-2.ogg` (high), `casino/card-slide-8.ogg` (high), `casino/card-slide-3.ogg` (high)
+- sequential item: `casino/card-slide-1.ogg` (medium), `casino/card-place-1.ogg` (high), `casino/card-fan-2.ogg` (high), `casino/card-slide-8.ogg` (high), `casino/card-slide-3.ogg` (high)
+- panel opening: `casino/cards-pack-open-1.ogg` (high), `casino/cards-pack-open-2.ogg` (high)
+- soft reveal: `casino/cards-pack-open-1.ogg` (high), `casino/cards-pack-open-2.ogg` (high)
+- success: `impact/impactBell_heavy_000.ogg` (medium), `impact/impactBell_heavy_003.ogg` (medium), `impact/impactBell_heavy_004.ogg` (medium)
+- logo payoff: `impact/impactBell_heavy_000.ogg` (medium), `impact/impactBell_heavy_003.ogg` (medium), `impact/impactBell_heavy_004.ogg` (medium)
+- reveal confirmation: `impact/impactBell_heavy_000.ogg` (medium), `impact/impactBell_heavy_003.ogg` (medium), `impact/impactBell_heavy_004.ogg` (medium)
+- major reveal: `impact/impactSoft_medium_001.ogg` (low), `impact/impactSoft_medium_004.ogg` (low), `impact/impactSoft_medium_002.ogg` (low), `impact/impactSoft_medium_003.ogg` (low), `impact/impactSoft_medium_000.ogg` (low)
+- hard transition: `impact/impactSoft_medium_001.ogg` (low), `impact/impactSoft_medium_004.ogg` (low), `impact/impactSoft_medium_002.ogg` (low), `impact/impactSoft_medium_003.ogg` (low), `impact/impactSoft_medium_000.ogg` (low)
+- chaotic accent: `interface/glitch_002.ogg` (low), `interface/error_005.ogg` (medium), `interface/error_006.ogg` (medium), `interface/glitch_004.ogg` (medium)
+
+## Family Summary
+
+- `casino/`: 51 files; HF risk low/medium/high = 0/10/41; avg high-frequency energy 0.59
+- `impact/`: 109 files; HF risk low/medium/high = 5/104/0; avg high-frequency energy 0.08
+- `interface/`: 20 files; HF risk low/medium/high = 5/14/1; avg high-frequency energy 0.25
+- `ui/`: 48 files; HF risk low/medium/high = 2/14/32; avg high-frequency energy 0.57
+
+## Selection Rules
+
+- Prefer low-risk SFX for repeated UI actions, text ticks, and dense sequences.
+- Use medium-risk SFX for isolated reveals or when the motion needs a crisp edge.
+- Avoid high-risk SFX for repeated ticks, long sequences, or polished/deadpan tones.
+- Treat continuous bright SFX as more fatiguing than sparse/textured bright SFX.
+- If using a bright SFX, keep it short, quiet, and isolated.
+- Match SFX timing to the visual landing or start depending on the gesture: clicks at press/start, reveals at resolution/payoff.

package/assets/motion/bin/contact-sheet.mjs

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+// EZ Motion contact sheet: tile frame PNGs into one labeled grid image so a
+// critique pass costs one image read instead of N (each image read re-prices
+// the whole context). `hf snapshot` already writes a full-size sheet; the
+// main use here is --phone, which shows the same frames at phone size.
+//
+// Usage: node contact-sheet.mjs <frames-dir> <out.jpg> [--cols 4] [--width 1600] [--phone]
+// Frames are ordered by the number in their filename (seconds or index).
+// Uses the `sharp` build that ships inside GG's bundled HyperFrames.
+import { readdir, stat } from "node:fs/promises";
+import { createRequire } from "node:module";
+import { basename, dirname, extname, join, resolve } from "node:path";
+
+function fail(message) {
+  process.stderr.write(`${message}\n`);
+  process.exit(1);
+}
+
+const args = process.argv.slice(2);
+const positional = args.filter((a, i) => !a.startsWith("--") && !args[i - 1]?.match(/^--(cols|width)$/));
+const [framesArg, outArg] = positional;
+if (!framesArg || !outArg) {
+  fail("usage: contact-sheet.mjs <frames-dir> <out.jpg> [--cols 4] [--width 1600] [--phone]");
+}
+const flag = (name, fallback) => {
+  const i = args.indexOf(`--${name}`);
+  const value = i >= 0 ? Number(args[i + 1]) : fallback;
+  if (!Number.isFinite(value) || value <= 0) fail(`--${name} must be a positive number`);
+  return value;
+};
+const phone = args.includes("--phone");
+const cols = flag("cols", phone ? 6 : 4);
+// A phone is ~390pt wide; a phone-strip cell is that width so text reads as it would on a feed.
+const sheetWidth = flag("width", phone ? 390 * cols : 1600);
+
+let sharp;
+try {
+  const require = createRequire(import.meta.url);
+  const hfPkg = require.resolve("hyperframes/package.json");
+  sharp = createRequire(hfPkg)("sharp");
+} catch {
+  fail("Contact sheets need the HyperFrames bundled with EZ. Reinstall EZ Coder to restore Motion mode.");
+}
+
+const framesDir = resolve(framesArg);
+const names = await readdir(framesDir).catch(() => fail(`Frames folder not found: ${framesDir}`));
+// Skip sheets from earlier runs (snapshot writes contact-sheet.jpg beside its frames).
+const entries = names.filter((n) => /\.(png|jpe?g|webp)$/i.test(n) && !/contact-sheet|phone-strip/i.test(n));
+if (entries.length === 0) fail(`No frame images in ${framesDir}`);
+const order = (name) => {
+  const m = basename(name, extname(name)).match(/(\d+(?:\.\d+)?)(?!.*\d)/);
+  return m ? Number(m[1]) : Number.POSITIVE_INFINITY;
+};
+entries.sort((a, b) => order(a) - order(b) || a.localeCompare(b));
+
+const gap = 8;
+const labelH = 28;
+const cellW = Math.floor((sheetWidth - gap * (cols + 1)) / cols);
+const first = await sharp(join(framesDir, entries[0])).metadata();
+const cellH = Math.round((cellW * (first.height ?? 9)) / (first.width ?? 16));
+const rows = Math.ceil(entries.length / cols);
+const height = gap + rows * (cellH + labelH + gap);
+
+const escapeXml = (s) => s.replace(/[<>&"']/g, (c) => `&#${c.charCodeAt(0)};`);
+const composites = [];
+for (const [i, name] of entries.entries()) {
+  const x = gap + (i % cols) * (cellW + gap);
+  const y = gap + Math.floor(i / cols) * (cellH + labelH + gap);
+  const tile = await sharp(join(framesDir, name))
+    .resize(cellW, cellH, { fit: "contain", background: "#111" })
+    .toBuffer();
+  composites.push({ input: tile, left: x, top: y });
+  const label = `${i + 1}. ${basename(name, extname(name))}`;
+  const svg = `<svg xmlns="http://www.w3.org/2000/svg" width="${cellW}" height="${labelH}"><text x="4" y="19" font-family="Helvetica, Arial, sans-serif" font-size="15" fill="#ddd">${escapeXml(label)}</text></svg>`;
+  composites.push({ input: Buffer.from(svg), left: x, top: y + cellH });
+}
+
+const out = resolve(outArg);
+const outStat = await stat(dirname(out)).catch(() => null);
+if (!outStat?.isDirectory()) fail(`Output folder does not exist: ${dirname(out)}`);
+await sharp({ create: { width: sheetWidth, height, channels: 3, background: "#1b1b1b" } })
+  .composite(composites)
+  .jpeg({ quality: 82 })
+  .toFile(out);
+process.stdout.write(
+  `${JSON.stringify({ ok: true, frames: entries.length, cols, width: sheetWidth, height, out })}\n`,
+);

package/assets/motion/bin/fonts.mjs

@@ -0,0 +1,107 @@
+#!/usr/bin/env node
+// EZ Motion font library: list the bundled OFL fonts, or install chosen
+// families into a video project so renders never depend on the network.
+//
+// Usage:
+//   node fonts.mjs list
+//   node fonts.mjs add <project-dir> <Family> [<Family> ...]
+//
+// `add` copies each family's woff2 files and OFL.txt into
+// <project>/assets/fonts/<family>/ and rewrites <project>/assets/fonts/fonts.css
+// with an @font-face for every bundled family installed there. Link it from
+// the composition <head>: <link rel="stylesheet" href="assets/fonts/fonts.css">.
+// Prints one JSON line: {"ok":true,...} or {"ok":false,"error":...}.
+import { copyFile, mkdir, readFile, stat, writeFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const LIBRARY = join(dirname(fileURLToPath(import.meta.url)), "..", "fonts");
+
+function done(result, code = 0) {
+  process.stdout.write(`${JSON.stringify(result)}\n`);
+  process.exit(code);
+}
+const fail = (error) => done({ ok: false, error }, 1);
+
+/** @returns {Promise<Array<{family:string,dir:string,license:string,files:Array<{file:string,style:string,weight:string,stretch:string|null}>}>>} */
+async function manifest() {
+  return JSON.parse(await readFile(join(LIBRARY, "fonts.json"), "utf8"));
+}
+
+function fontFace(entry, file) {
+  const lines = [
+    `  font-family: "${entry.family}";`,
+    `  src: url("${entry.dir}/${file.file}") format("woff2");`,
+    `  font-style: ${file.style};`,
+    `  font-weight: ${file.weight};`,
+  ];
+  if (file.stretch) lines.push(`  font-stretch: ${file.stretch};`);
+  lines.push("  font-display: block;");
+  return `@font-face {\n${lines.join("\n")}\n}`;
+}
+
+const [command, ...rest] = process.argv.slice(2);
+const fonts = await manifest().catch(() => fail(`Font library missing at ${LIBRARY}`));
+
+if (command === "list") {
+  done({
+    ok: true,
+    specimen: join(LIBRARY, "specimen.jpg"),
+    families: fonts.map((f) => ({
+      family: f.family,
+      styles: f.files.map((file) => file.style),
+      weight: f.files[0]?.weight,
+      width: f.files[0]?.stretch ?? null,
+    })),
+  });
+}
+
+if (command !== "add" || rest.length < 2) {
+  fail("usage: fonts.mjs list | fonts.mjs add <project-dir> <Family> [<Family> ...]");
+}
+
+const [projectArg, ...names] = rest;
+const project = resolve(projectArg);
+const projectInfo = await stat(project).catch(() => undefined);
+if (!projectInfo?.isDirectory()) fail(`Project folder not found: ${project}`);
+
+const byName = new Map(fonts.map((f) => [f.family.toLowerCase(), f]));
+const chosen = [];
+for (const name of names) {
+  const entry = byName.get(name.toLowerCase());
+  if (!entry) {
+    fail(`Unknown family "${name}". Bundled: ${fonts.map((f) => f.family).join(", ")}`);
+  }
+  chosen.push(entry);
+}
+
+const target = join(project, "assets", "fonts");
+for (const entry of chosen) {
+  const dir = join(target, entry.dir);
+  await mkdir(dir, { recursive: true });
+  for (const file of [...entry.files.map((f) => f.file), "OFL.txt"]) {
+    await copyFile(join(LIBRARY, entry.dir, file), join(dir, file));
+  }
+}
+
+// Rebuild the stylesheet from everything installed, so repeated `add` calls
+// accumulate families instead of dropping earlier ones.
+const installed = [];
+for (const entry of fonts) {
+  const present = await stat(join(target, entry.dir, entry.files[0]?.file ?? "")).catch(
+    () => undefined,
+  );
+  if (present) installed.push(entry);
+}
+const css = [
+  "/* Generated by EZ Motion fonts.mjs. SIL OFL 1.1: licenses sit beside each family. */",
+  ...installed.flatMap((entry) => entry.files.map((file) => fontFace(entry, file))),
+].join("\n\n");
+await writeFile(join(target, "fonts.css"), `${css}\n`);
+
+done({
+  ok: true,
+  installed: installed.map((f) => f.family),
+  stylesheet: join(target, "fonts.css"),
+  link: '<link rel="stylesheet" href="assets/fonts/fonts.css" />',
+});

package/assets/motion/bin/hyperframes.mjs

@@ -0,0 +1,122 @@
+#!/usr/bin/env node
+// EZ Motion's HyperFrames launcher.
+//
+// EZ ships one pinned HyperFrames CLI with the app and one matching set of
+// skills (../plugin.json carries the version). This launcher is the only way
+// Motion runs the CLI: it resolves the bundled package from its own location,
+// so it never downloads a different release through npx, and it pins the same
+// environment HyperFrames' own plugin launcher does (no standalone skill
+// installs, no update checks). It also opts out of CLI telemetry.
+//
+// Usage: node hyperframes.mjs <hyperframes command> [args...]
+//        node hyperframes.mjs --script <absolute-script-path> [args...]
+import { spawn } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { delimiter, dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const bundleRoot = fileURLToPath(new URL("../", import.meta.url));
+
+/** The release version EZ bundled the skills for. */
+function bundledVersion() {
+  const manifest = JSON.parse(readFileSync(join(bundleRoot, "plugin.json"), "utf8"));
+  if (manifest.name !== "hyperframes" || typeof manifest.version !== "string") {
+    throw new Error(`Invalid EZ Motion manifest: ${join(bundleRoot, "plugin.json")}`);
+  }
+  return manifest.version;
+}
+
+/** Absolute path of the bundled CLI entry, plus its installed version. */
+function resolveCli() {
+  const require = createRequire(import.meta.url);
+  let pkgPath;
+  try {
+    pkgPath = require.resolve("hyperframes/package.json");
+  } catch {
+    throw new Error(
+      "The HyperFrames CLI bundled with EZ is missing. Reinstall EZ Coder to restore Motion mode.",
+    );
+  }
+  const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+  const bin = typeof pkg.bin === "string" ? pkg.bin : pkg.bin?.hyperframes;
+  if (typeof bin !== "string") throw new Error(`No hyperframes bin in ${pkgPath}`);
+  return { entry: join(dirname(pkgPath), bin), version: pkg.version };
+}
+
+/**
+ * Private by default: `snapshot` and `capture` send frames/images to Google,
+ * OpenRouter or Vertex automatically whenever those API keys exist in the
+ * user's environment. Opt out unless the caller asked for the analysis.
+ * `add` copies a snippet to the system clipboard by default, which would
+ * silently overwrite whatever the user had copied; the snippet is also
+ * printed, so the agent never needs the clipboard.
+ */
+function withPrivacyDefaults(args) {
+  const has = (flag) => args.some((a) => a === flag || a.startsWith(`${flag}=`));
+  if (args[0] === "snapshot" && !has("--describe")) return [...args, "--describe", "false"];
+  if (args[0] === "capture" && !has("--skip-vision") && !has("--vision")) {
+    return [...args, "--skip-vision"];
+  }
+  if (args[0] === "add" && !has("--clipboard") && !has("--no-clipboard")) {
+    return [...args, "--no-clipboard"];
+  }
+  return args;
+}
+
+function main(rawArgs) {
+  const args = withPrivacyDefaults(rawArgs);
+  if (args[0] === "skills") {
+    throw new Error(
+      "HyperFrames skills are bundled with EZ Motion and update with EZ releases. Do not install or update them.",
+    );
+  }
+  const version = bundledVersion();
+  const cli = resolveCli();
+  if (cli.version !== version) {
+    process.stderr.write(
+      `warning: bundled HyperFrames CLI ${cli.version} differs from the skills release ${version}\n`,
+    );
+  }
+
+  // Put the running Node first on PATH so anything the CLI or a helper script
+  // spawns as `node` uses this runtime, even on machines without Node installed.
+  const nodeDir = dirname(process.execPath);
+  const env = {
+    ...process.env,
+    PATH: [nodeDir, process.env.PATH ?? ""].filter(Boolean).join(delimiter),
+    HYPERFRAMES_SKIP_SKILLS: "1",
+    HYPERFRAMES_SKILL_PKG_VERSION: version,
+    HYPERFRAMES_PLUGIN_VERSION: version,
+    HYPERFRAMES_NO_UPDATE_CHECK: "1",
+    HYPERFRAMES_NO_AUTO_INSTALL: "1",
+    HYPERFRAMES_NO_TELEMETRY: "1",
+  };
+
+  let childArgs;
+  if (args[0] === "--script") {
+    if (!args[1]) throw new Error("--script requires a Node script path.");
+    childArgs = args.slice(1);
+  } else {
+    childArgs = [cli.entry, ...args];
+  }
+
+  const child = spawn(process.execPath, childArgs, { env, stdio: "inherit", windowsHide: true });
+  for (const signal of ["SIGINT", "SIGTERM", "SIGHUP"]) {
+    process.on(signal, () => child.kill(signal));
+  }
+  child.on("error", (error) => {
+    process.stderr.write(`${error.message}\n`);
+    process.exitCode = 1;
+  });
+  child.on("exit", (code, signal) => {
+    process.exitCode = code ?? (signal ? 1 : 0);
+  });
+}
+
+try {
+  main(process.argv.slice(2));
+} catch (error) {
+  process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+  process.exitCode = 1;
+}