Skip to content

secondsky/claude-skills / plugins/clefcut-cloudflare-video/skills/clefcut-cloudflare-video

clefcut-cloudflare-video

Verified

Cut long videos into clips for YouTube, YouTube Shorts, TikTok, Instagram Reels, X (Twitter), and similar creator platforms. Free local scene, silence, and OCR analysis; Cloudflare CLEF rating; verified ffmpeg cuts. Use when repurposing long video.

FileKindSize
SKILL.mdskill md20.5 KB
references/ai-gateway-and-mcp.mdmarkdown5.6 KB
references/clairic.mdmarkdown7.9 KB
references/clef.mdmarkdown11.2 KB
references/clip-selection.mdmarkdown6.5 KB
references/platform-specs.mdmarkdown12.6 KB
references/workflow.mdmarkdown15.9 KB
scripts/clipcut.mjsexecutablescript205.3 KB
templates/env.exampleother588 B
templates/questions.example.jsonconfig2.5 KB

scripts/clipcut.mjs

View on GitHub
#!/usr/bin/env node
// clipcut.mjs — cut long videos into social/creator clips: FREE local analysis first
// (probe / segments / sheets / cut / tighten / export / check / preview), Cloudflare
// Workers AI second (CLEF = rate contact sheets, CLAIRIC = read burned-in text),
// verified ffmpeg cutting and platform export last. Single file, zero npm
// dependencies (node: builtins; tesseract.js used opportunistically when present).
// Node 18+. MIT license.
//
// Credits / design lineage:
//   - Infrastructure (env layering, ffmpeg discovery, batching, retry shape, cost gate)
//     adapted from Levanto Labs SageCut (MIT) via the sibling video-qa.mjs skill.
//   - Tolerance-based cutting (try -c copy, measure, re-encode when off), silence
//     removal with kept margins, and the platform compliance-check idea are inspired
//     by kajisho5/ffmpeg-skill (MIT).
//   - The rate rubric (questions.json pass/escalate semantics) follows melvynx's
//     rubric style from the sibling skill.
//
// Env (process env wins, then <cwd>/.env, then ~/.clefcut/.env; values never printed):
//   CLOUDFLARE_ACCOUNT_ID, CLOUDFLARE_API_TOKEN (Workers AI: Read, plus Edit unless the
//   token was created from the dashboard template), CLEFCUT_GATEWAY_ID (optional AI
//   Gateway id), CLEFCUT_FFMPEG / CLEFCUT_FFPROBE (optional binary paths), CLEFCUT_YES=1
//   (acts like passing --yes to the cost gate).
//
// Examples:
//   node clipcut.mjs doctor --ping
//   node clipcut.mjs probe talk.mp4 --out probe.json
//   node clipcut.mjs segments probe.json --min 15 --max 90 --count 10
//   node clipcut.mjs sheets talk.mp4 --segments segments.json --out sheets/
//   node clipcut.mjs rate --sheets sheets/ --questions questions.json --model clef-flash
//   node clipcut.mjs read talk.mp4 --segments segments.json --engine auto
//   node clipcut.mjs cut talk.mp4 --plan clips.json --tolerance 0.5
//   node clipcut.mjs tighten clips/hook.mp4
//   node clipcut.mjs export clips/hook.mp4 --platform shorts --variant 9x16-crop --loudnorm
//   node clipcut.mjs check exports/hook_shorts_9x16-crop.mp4 --platform shorts
//   node clipcut.mjs preview clips/hook.mp4 --source talk.mp4 --start 12.5 --end 58.2
//   node clipcut.mjs plan --file clips.json
//   node clipcut.mjs --selftest

import fs from 'node:fs';
import path from 'node:path';
import os from 'node:os';
import process from 'node:process';
import crypto from 'node:crypto';
import { spawn } from 'node:child_process';
import { createRequire } from 'node:module';
import { pathToFileURL } from 'node:url';

// ---------------------------------------------------------------- constants

const RATE_STATE_TEMPLATE = 'Contact sheet of {N} evenly-spaced frames from one candidate segment of a longer video, reading order left-to-right top-to-bottom. Answer about the segment as a whole.';
const READ_STATE = 'One frame from the middle of a candidate segment of a longer video. Answer from what is visible in this frame.';
const READ_STATE_SHEET = 'A contact sheet of evenly-spaced frames from one candidate segment of a longer video, reading order left-to-right top-to-bottom. Answer about the segment as a whole from what is visible in the sheet.';
const PRICES = { clef: 0.24, 'clef-flash': 0.038, 'clef-omni': 0.15, clairic: 0.10 }; // $/Mtok input; output free
const MAX_IMAGES = 4;                        // API hard cap per request
const MAX_IMAGE_BYTES = 4 * 1024 * 1024;     // 4 MiB per image (fact sheet)
const BATCH_BYTES = 6 * 1024 * 1024;         // pre-split raw PNG bytes per request (8 MiB decoded / 13 MiB body caps)
const GATE_MAX_IMAGES = 240;                 // above this, rate/read(clairic) need --yes
const PACE_MS = 300;                         // minimum delay between API requests
const CHOICE_CONF_FLOOR = 0.5;               // choice answers below this confidence escalate
const TIMEOUT_MS = 120_000;
const RETRIES = 3;                           // 429/5xx: backoff 1s, 2s, 4s (retry-after honored, capped 60s)
const SCENE_THRESHOLD = 0.4;                 // default scene-score cutoff for scene_changes
const SCENE_MAX_CHANGES = 64;                // keep at most this many scene-change points
const SILENCE_FILTER = 'silencedetect=noise=-35dB:d=0.5';
const FADE_S = 0.03;                         // 30 ms audio fades on accurate re-encodes / tighten joins
const SILENT_MAX_DB = -80;                   // one digital-silence tripwire: max volume at/below this = dead audio
const FP_REGION_BYTES = 8 * 1024 * 1024;     // input fingerprint: sha256 of the first AND last 8 MiB

/**
 * Gain expression for a 30 ms de-click at a tighten JOIN (output timeline):
 * ramp down into c, ramp up out of c, gain 1 everywhere else. NOT afade —
 * afade=t=in with st>0 silences everything before st, which would zero every
 * earlier kept piece. Evaluate at t=c: between() is inclusive so the first
 * branch wins and yields 0 — continuous on both sides of the dip.
 */
export function fadeJoinExpr(c, fadeS = FADE_S) {
  return `if(between(t,${fmt(c - fadeS)},${fmt(c)}),(${fmt(c)}-t)/${fadeS},if(between(t,${fmt(c)},${fmt(c + fadeS)}),(t-${fmt(c)})/${fadeS},1))`;
}

const LOUDNORM_TARGET = { I: -14, TP: -1.5, LRA: 11 };
const PLATFORMS = ['youtube', 'shorts', 'tiktok', 'reels', 'x', 'creator'];
const VARIANTS = ['original', '9x16-crop', '9x16-blur'];
const TIGHTEN_DEFAULTS = { thresholdDb: -35, minSilenceS: 0.6, marginS: 0.15, minKeepS: 0.2, maxCuts: 400 };
const DEFAULT_TEXT_FIELDS = { onscreen_text: { type: 'text', instructions: 'All text visible in the frame, in reading order' } };
const IS_WIN = process.platform === 'win32';
const EXE = IS_WIN ? '.exe' : '';
const EXPORT_NAME_RE = new RegExp(`^[A-Za-z0-9._-]+_(${PLATFORMS.join('|')})_(${VARIANTS.join('|')})\\.mp4$`);
const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
const readJson = (p) => JSON.parse(fs.readFileSync(p, 'utf8'));
const fmt = (n) => String(+(+n).toFixed(3));

class UserError extends Error {}

// ---------------------------------------------------------------- env + redaction

/** Parse .env text into a KEY=VALUE map. Handles comments, quotes, `export `. */
export function parseEnvText(text) {
  const out = {};
  for (const raw of String(text || '').split(/\r?\n/)) {
    const line = raw.trim().replace(/^export\s+/, '');
    if (!line || line.startsWith('#')) continue;
    const eq = line.indexOf('=');
    if (eq <= 0) continue;
    const key = line.slice(0, eq).trim();
    let val = line.slice(eq + 1).trim();
    if ((val.startsWith('"') && val.endsWith('"')) || (val.startsWith("'") && val.endsWith("'"))) val = val.slice(1, -1);
    else { const c = val.indexOf(' #'); if (c > 0) val = val.slice(0, c).trim(); }
    if (/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) out[key] = val;
  }
  return out;
}

/**
 * Layer .env file contents under the process env. `layers` is ordered LOWEST precedence
 * first (home .env, then project .env so the project wins); process env always wins.
 * Returns { env, sources } where sources maps each file-provided key to its label.
 */
export function mergeEnvLayered(processEnv, layers) {
  const file = {};
  const sources = {};
  for (const { text, label } of layers || []) {
    for (const [k, v] of Object.entries(parseEnvText(text || ''))) {
      file[k] = v;
      sources[k] = label;
    }
  }
  return { env: { ...file, ...processEnv }, sources };
}

let ENV_CACHE = null;
const PROJ_ENV_PATH = () => path.join(process.cwd(), '.env');
const HOME_ENV_PATH = () => path.join(os.homedir(), '.clefcut', '.env');
const readTextOrNull = (p) => { try { return fs.readFileSync(p, 'utf8'); } catch { return null; } };
function mergedEnv() {
  if (ENV_CACHE) return ENV_CACHE;
  const home = HOME_ENV_PATH();
  const proj = PROJ_ENV_PATH();
  ENV_CACHE = mergeEnvLayered(process.env, [
    { text: readTextOrNull(home), label: home },   // home first...
    { text: readTextOrNull(proj), label: proj },   // ...so the project file overrides it
  ]);
  return ENV_CACHE;
}

/** Where a config value came from: "process env", a file path, or null. Never the value. */
function envSource(key) {
  if (process.env[key] != null && process.env[key] !== '') return 'process env';
  return (mergedEnv().sources || {})[key] || null;
}

const cfg = () => {
  const e = mergedEnv().env;
  return { accountId: e.CLOUDFLARE_ACCOUNT_ID || '', token: e.CLOUDFLARE_API_TOKEN || '', gateway: e.CLEFCUT_GATEWAY_ID || '' };
};

function requireCreds() {
  const c = cfg();
  if (!c.accountId || !c.token) throw new UserError('CLOUDFLARE_ACCOUNT_ID and CLOUDFLARE_API_TOKEN are required (process env, ./.env or ~/.clefcut/.env). Run "clipcut.mjs doctor".');
}

const yesFlag = (o) => o.yes === true || String(mergedEnv().env.CLEFCUT_YES ?? '').trim() === '1';

/** Replace the API token (and account id) anywhere in a string so it can never be printed. */
export function redact(s) {
  const { token, accountId } = cfg();
  let out = String(s);
  if (token && token.length >= 8) out = out.split(token).join('***REDACTED***');
  if (accountId && accountId.length >= 8) out = out.split(accountId).join('***ACCOUNT***');
  return out;
}

// ---------------------------------------------------------------- small pure helpers

export function chunkAll(arr, n) {
  const out = [];
  for (let i = 0; i < arr.length; i += n) out.push(arr.slice(i, i + n));
  return out;
}

/** Classify one answer. p = defect probability (higher = worse), t = pass threshold, margin = escalate band below t. */
export function classify(p, t, margin = 0.3, escalateOnly = false) {
  if (p == null || !Number.isFinite(p)) return 'escalate';
  if (t == null) return 'pass';
  if (p >= t) return escalateOnly ? 'escalate' : 'fail';
  if (p >= t - margin) return 'escalate';
  return 'pass';
}

/** Defect probability (higher = worse). noul: p(yes). score: level/(levels-1). choice: p of "defect_options". */
export function defectProb(q, a) {
  if (!a) return null;
  if (q.type === 'noul') return typeof a.noul === 'number' ? a.noul : null;
  if (q.type === 'score') { const n = q.criteria.length - 1; return typeof a.score === 'number' && n > 0 ? a.score / n : null; }
  if (q.type === 'choice') {
    if (!Array.isArray(q.defect_options) || !q.defect_options.length) return a.choice == null ? null : 0;
    const probs = a.probabilities || {};
    return Math.max(...q.defect_options.map((k) => (typeof probs[k] === 'number' ? probs[k] : 0)), 0);
  }
  return null;
}

/** Full classification of one raw answer: defect probability + the fixed choice-confidence floor. */
export function classifyAnswer(q, raw, passT, margin = 0.3, escalateOnly = false) {
  const cls = classify(defectProb(q, raw), passT, margin, escalateOnly);
  // Choice answers escalate on low confidence against a FIXED 0.5 floor — never the pass threshold.
  if (q.type === 'choice' && cls === 'pass' && raw && typeof raw.confidence === 'number' && raw.confidence < CHOICE_CONF_FLOOR) return 'escalate';
  return cls;
}

/**
 * Split files into request batches: at most `size` files AND at most `maxBytes` of raw PNG
 * bytes per batch (starts a new batch when the next file would overflow). Keeps requests
 * under the 8 MiB decoded / 13 MiB body caps without waiting for a 413.
 */
export function buildBatches(files, { size = MAX_IMAGES, maxBytes = BATCH_BYTES, sizeOf = null } = {}) {
  const max = Math.max(1, size);
  const sz = sizeOf || ((f) => { try { return fs.statSync(f.path).size; } catch { return 0; } });
  const out = [];
  let cur = [];
  let curBytes = 0;
  for (const f of files) {
    const b = sz(f);
    if (cur.length && (cur.length + 1 > max || curBytes + b > maxBytes)) { out.push(cur); cur = []; curBytes = 0; }
    cur.push(f);
    curBytes += b;
  }
  if (cur.length) out.push(cur);
  return out;
}

/** Rough input tokens for one image: (w/32)*(h/32)+3, capped 1024; 600 (~960px class) when size unknown. */
export function estTokensPerFrame(w, h) {
  if (!Number.isFinite(w) || !Number.isFinite(h) || w <= 0 || h <= 0) return 600;
  return Math.min(1024, Math.max(1, Math.round(w / 32)) * Math.max(1, Math.round(h / 32)) + 3);
}

// ---------------------------------------------------------------- fingerprints + rotation (pure)

/** sha256 of a buffer, hex. */
export function sha256Hex(buf) {
  return crypto.createHash('sha256').update(buf).digest('hex');
}

/**
 * "head:tail" sha256 hex pair over the first and last `region` bytes of a buffer
 * (pure — the selftests feed fixed buffers). For buffers smaller than 2*region the
 * two windows overlap; that is fine, they are hashed independently.
 */
export function headTailHash(buf, region = FP_REGION_BYTES) {
  const b = Buffer.isBuffer(buf) ? buf : Buffer.from(buf);
  const n = Math.max(0, Math.min(region, b.length));
  const head = b.subarray(0, n);
  const tail = b.subarray(b.length - n);
  return `${sha256Hex(head)}:${sha256Hex(tail)}`;
}

/**
 * Input fingerprint: file size in bytes + the "head:tail" sha256 pair over the
 * first/last 8 MiB. A re-render at the same path with the same duration still
 * changes bytes in the head region, so the pair catches swapped files the
 * path/duration warnings miss.
 */
export function fingerprintFile(file) {
  const st = fs.statSync(file);
  let fd;
  try {
    fd = fs.openSync(file, 'r');
    const n = Math.min(FP_REGION_BYTES, st.size);
    const head = Buffer.alloc(n);
    if (n > 0) fs.readSync(fd, head, 0, n, 0);
    const tail = Buffer.alloc(n);
    if (n > 0) fs.readSync(fd, tail, 0, n, Math.max(0, st.size - n));
    return { size: st.size, sha256_head_tail: `${sha256Hex(head)}:${sha256Hex(tail)}` };
  } finally {
    if (fd != null) fs.closeSync(fd);
  }
}

/** Fingerprint verdict: true = match, false = MISMATCH, null = not comparable (either side absent). */
export function fingerprintsMatch(a, b) {
  if (!a || !b || a.size == null || b.size == null || !a.sha256_head_tail || !b.sha256_head_tail) return null;
  return a.size === b.size && a.sha256_head_tail === b.sha256_head_tail;
}

/**
 * Signed rotation degrees from an ffprobe stream's side_data_list Display Matrix
 * entry, normalized to (-180, 180]; null when absent or zero. The sign convention
 * varies by producer — only |rot| % 180 === 90 matters for the dimension swap.
 */
export function streamRotation(stream) {
  const list = stream && Array.isArray(stream.side_data_list) ? stream.side_data_list : [];
  let raw = null;
  for (const sd of list) {
    if (!sd || !('rotation' in sd)) continue;
    const n = Number(sd.rotation);
    if (Number.isFinite(n)) { raw = n; break; }
  }
  if (raw == null) return null;
  const norm = ((raw % 360) + 360) % 360;
  const signed = norm > 180 ? norm - 360 : norm;
  return signed === 0 ? null : signed;
}

/** Display dimensions after rotation metadata: at ±90/±270 width/height swap.
 * Returns { width, height, rotated } — non-numeric input keeps null dims. */
export function displayDimsForRotation(width, height, rotation) {
  const w = Number(width); const h = Number(height);
  const r = Number(rotation);
  const rotated = Number.isFinite(r) && Math.abs(r) % 180 === 90;
  const okW = Number.isFinite(w) && w > 0;
  const okH = Number.isFinite(h) && h > 0;
  if (rotated && okW && okH) return { width: h, height: w, rotated: true };
  return { width: okW ? w : null, height: okH ? h : null, rotated: false };
}

// ---------------------------------------------------------------- ffmpeg (Remotion compositor first)

let FFMPEG_CACHE = null;

function compositorDirs(root) {
  const dirs = [];
  let dir = path.resolve(root);
  for (;;) {
    const nm = path.join(dir, 'node_modules', '@remotion');
    try { for (const e of fs.readdirSync(nm)) if (/^compositor-/.test(e)) dirs.push(path.join(nm, e)); } catch { /* not here */ }
    const up = path.dirname(dir);
    if (up === dir) return dirs;
    dir = up;
  }
}

/** One @remotion/compositor-* package as a candidate toolchain (no spawn test here). */
function compositorCandidate(pkgDir) {
  const pick = (names) => names.map((n) => path.join(pkgDir, n)).find((p) => fs.existsSync(p) && fs.statSync(p).isFile());
  const ffmpeg = pick([`ffmpeg${EXE}`, path.join('bin', `ffmpeg${EXE}`)]);
  if (!ffmpeg) return null;
  const ffprobe = pick([`ffprobe${EXE}`, path.join('bin', `ffprobe${EXE}`)]) || `ffprobe${EXE}`;
  const env = { ...process.env };
  const lib = [path.dirname(ffmpeg), path.join(pkgDir, 'lib'), path.join(pkgDir, 'bin')].filter((p) => fs.existsSync(p)).join(':');
  if (process.platform === 'darwin') env.DYLD_LIBRARY_PATH = [lib, env.DYLD_LIBRARY_PATH].filter(Boolean).join(':');
  else if (process.platform === 'linux') env.LD_LIBRARY_PATH = [lib, env.LD_LIBRARY_PATH].filter(Boolean).join(':');
  else if (IS_WIN) env.PATH = [lib, env.PATH || env.Path].filter(Boolean).join(';');
  return { ffmpeg, ffprobe, env, source: `remotion:${path.basename(pkgDir)}` };
}

/**
 * Resolve the ffmpeg toolchain: env override, then every @remotion/compositor-* candidate
 * (spawn-tested; failures fall through to the next), then system PATH. The first binary
 * that actually runs `ffmpeg -version` wins.
 */
async function locate() {
  if (FFMPEG_CACHE) return FFMPEG_CACHE;
  const candidates = [];
  if (process.env.CLEFCUT_FFMPEG) {
    candidates.push({ ffmpeg: process.env.CLEFCUT_FFMPEG, ffprobe: process.env.CLEFCUT_FFPROBE || path.join(path.dirname(process.env.CLEFCUT_FFMPEG), `ffprobe${EXE}`), env: { ...process.env }, source: 'env (CLEFCUT_FFMPEG)' });
  }
  for (const pkgDir of compositorDirs(process.cwd()).sort()) {
    const c = compositorCandidate(pkgDir);
    if (c) candidates.push(c);
  }
  candidates.push({ ffmpeg: `ffmpeg${EXE}`, ffprobe: `ffprobe${EXE}`, env: { ...process.env }, source: 'PATH' });
  let last = null;
  for (const c of candidates) {
    last = c;
    try {
      const v = await runExe(c.ffmpeg, ['-version'], { env: c.env });
      if (v.code === 0) { c.version = v.stdout.toString().split('\n')[0]; return (FFMPEG_CACHE = c); }
    } catch { /* spawn/access failure — try the next candidate */ }
  }
  return (FFMPEG_CACHE = last); // PATH fallback; downstream errors surface naturally
}

/** Run a binary, collect stdout/stderr; optionally write `input` to stdin (drain first: no pipe
 * deadlock). stderr is capped (it is for error messages only) — high-volume parses must target
 * STDOUT (collected as unbounded buffers) or a temp file, NEVER stderr, or a long video
 * silently loses the head of its output. */
function runExe(exe, args, { env = process.env, input = null } = {}) {
  return new Promise((resolve, reject) => {
    const p = spawn(exe, args, { env, windowsHide: true });
    const out = []; let err = '';
    p.stdout.on('data', (d) => out.push(d));
    p.stderr.on('data', (d) => { err += d.toString(); if (err.length > 400_000) err = err.slice(-200_000); });
    p.on('error', (e) => reject(new UserError(`${exe} could not start: ${e.message}. Run "clipcut.mjs doctor".`)));
    p.on('close', (code) => resolve({ code, stdout: Buffer.concat(out), stderr: err }));
    if (input) p.stdin.end(input); else p.stdin.end();
  });
}

const runFf = async (bin, args, opts = {}) => {
  const loc = await locate();
  return runExe(bin === 'ffprobe' ? loc.ffprobe : loc.ffmpeg, args, { ...opts, env: loc.env });
};

/** Container facts via ffprobe: duration, dimensions, fps (avg first), VFR guess, audio presence.
 * width/height are DISPLAY dims: rotation metadata (tkhd display matrix, read from
 * stream.side_data_list[].rotation) swaps them at ±90/±270 — ffmpeg autorotates on
 * decode, so downstream filter math and aspect checks must use the display dims. */
async function probeContainer(file) {
  const r = await runFf('ffprobe', ['-v', 'error', '-show_streams', '-show_format', '-of', 'json', file]);
  if (r.code !== 0) throw new UserError(`ffprobe failed on ${file}: ${r.stderr.trim().slice(0, 300)}`);
  const j = JSON.parse(r.stdout.toString());
  const v = (j.streams || []).find((s) => s.codec_type === 'video');
  if (!v) throw new UserError(`${file} has no video stream.`);
  const rate = (s) => { const [n, d] = String(s || '0/1').split('/').map(Number); return d ? n / d : n || 0; };
  const rFps = rate(v.r_frame_rate);
  const avgFps = rate(v.avg_frame_rate);
  const duration = Number(j.format && j.format.duration) || Number(v.duration) || 0;
  const rotation = streamRotation(v);
  const dims = displayDimsForRotation(v.width, v.height, rotation);
  return {
    width: dims.width, height: dims.height,
    codedWidth: Number.isFinite(Number(v.width)) ? Number(v.width) : null,
    codedHeight: Number.isFinite(Number(v.height)) ? Number(v.height) : null,
    rotation, rotated: dims.rotated,
    fps: avgFps || rFps || 30, r_frame_rate: rFps, avg_frame_rate: avgFps,
    vfr: rFps > 0 && avgFps > 0 && Math.abs(rFps - avgFps) > 0.5,
    hasAudio: (j.streams || []).some((s) => s.codec_type === 'audio'),
    codec: v.codec_name || null, pixFmt: v.pix_fmt || null,
    duration,
  };
}

/** Facts for the `check` subcommand: one ffprobe pass (container + streams) plus, when an
 * audio stream exists, volumedetect (levels/silence) and loudness (loudnorm JSON with the
 * ebur128 fallback). Unmeasurable facts stay null — never guessed. A hard ffprobe failure
 * throws; a file with no video stream returns measurable: false (rows become WARNs). */
async function probeCheckFacts(file) {
  const r = await runFf('ffprobe', ['-v', 'error', '-show_streams', '-show_format', '-of', 'json', file]);
  if (r.code !== 0) throw new UserError(`ffprobe failed on ${file}: ${r.stderr.trim().slice(0, 300)}`);
  const j = JSON.parse(r.stdout.toString());
  const v = (j.streams || []).find((s) => s.codec_type === 'video') || null;
  const a = (j.streams || []).find((s) => s.codec_type === 'audio') || null;
  const num = (x) => { const n = Number(x); return Number.isFinite(n) ? n : null; };
  const rate = (s) => { const [n, d] = String(s || '0/1').split('/').map(Number); return d ? n / d : n || 0; };
  const durRaw = num(j.format && j.format.duration) ?? (v ? num(v.duration) : null);
  const rFps = v ? rate(v.r_frame_rate) : 0;
  const avgFps = v ? rate(v.avg_frame_rate) : 0;
  // The moov-box walk only means something on ISO-BMFF containers (mp4/mov family);
  // on anything else faststart is unmeasurable (null), never a false FAIL.
  const container = String((j.format && j.format.format_name) || '');
  const isIsoBmff = /mp4|mov|m4a|3gp|m4v/.test(container);
  let sizeBytes = null;
  try { sizeBytes = fs.statSync(file).size; } catch { /* keep null */ }
  // Display dims: rotation metadata swaps width/height at ±90/±270 (probeContainer parity).
  const rotation = v ? streamRotation(v) : null;
  const dims = v ? displayDimsForRotation(v.width, v.height, rotation) : { width: null, height: null };
  const facts = {
    file,
    measurable: !!v,
    duration: durRaw != null && durRaw > 0 ? +durRaw.toFixed(3) : null,
    width: dims.width,
    height: dims.height,
    rotation,
    fps: avgFps || rFps || null,
    vfr: !!(rFps > 0 && avgFps > 0 && Math.abs(rFps - avgFps) > 0.5),
    videoCodec: v ? v.codec_name || null : null,
    pixFmt: v ? v.pix_fmt || null : null,
    hasAudio: !!a,
    audioCodec: a ? a.codec_name || null : null,
    audioSampleRate: a ? num(a.sample_rate) : null,
    faststart: isIsoBmff ? hasFaststart(file) : null,
    loudness: null,
    silentAudio: null,
    audioMaxDb: null,
    sizeBytes,
  };
  if (a) {
    const rv = await runFf('ffmpeg', ['-i', file, '-vn', '-af', 'volumedetect', '-f', 'null', '-']);
    const vol = parseVolumedetect(rv.stderr);
    if (vol) {
      facts.audioMaxDb = vol.max;
      facts.silentAudio = vol.max != null ? vol.max <= SILENT_MAX_DB : null;
    }
    const rl = await runFf('ffmpeg', ['-i', file, '-af', 'loudnorm=print_format=json', '-f', 'null', '-']);
    facts.loudness = parseLoudnormJson(rl.stderr);
    if (!facts.loudness) {
      const re = await runFf('ffmpeg', ['-i', file, '-af', 'ebur128=peak=true', '-f', 'null', '-']);
      facts.loudness = parseEbur128(re.stderr);
    }
  }
  return facts;
}

/** Pixel dimensions of an image file (ffprobe), or nulls. */
async function imageDims(img) {
  try {
    const r = await runFf('ffprobe', ['-v', 'error', '-show_streams', '-of', 'json', img]);
    const s = JSON.parse(r.stdout.toString()).streams[0];
    if (s && s.width) return { width: s.width, height: s.height };
  } catch { /* fall through */ }
  return { width: null, height: null };
}

// ---------------------------------------------------------------- ffmpeg output parsers (pure)

/** Escape a path for use as a filtergraph option value (metadata=print:file=...). */
export function escapeFilterPath(p) {
  return String(p).replace(/\\/g, '\\\\').replace(/:/g, '\\:').replace(/'/g, "\\'");
}

/** Parse `metadata=print` output: "frame:N pts:P pts_time:T" lines followed by "lavfi.scene_score=S". */
export function parseSceneMetadata(text) {
  const out = [];
  let t = null;
  for (const line of String(text || '').split(/\r?\n/)) {
    const pt = /pts_time:(-?[\d.]+)/.exec(line);
    if (pt) { t = Number(pt[1]); continue; }
    const sc = /lavfi\.scene_score=([\d.eE+-]+)/.exec(line);
    if (sc) out.push({ t: Number.isFinite(t) ? t : null, score: Number(sc[1]) });
  }
  return out;
}

/** Keep the top `cap` local maxima with score >= threshold, returned as ascending timestamps. */
export function sceneMaxima(scenes, threshold = SCENE_THRESHOLD, cap = SCENE_MAX_CHANGES) {
  const c = (scenes || []).filter((s) => s && Number.isFinite(s.t) && Number.isFinite(s.score));
  const peaks = c.filter((s, i) =>
    s.score >= threshold
    && (i === 0 || s.score >= c[i - 1].score)
    && (i === c.length - 1 || s.score > c[i + 1].score));
  return peaks.slice().sort((a, b) => b.score - a.score).slice(0, Math.max(1, cap)).sort((a, b) => a.t - b.t).map((s) => +s.t.toFixed(3));
}

/**
 * Boundary verdict from ONE window's scene scan (absolute timestamps): the max scene score
 * in the window, and whether any scene-change peak lands within `nearS` seconds of t.
 */
export function boundaryScan(windowScenes, t, { threshold = SCENE_THRESHOLD, nearS = 0.5 } = {}) {
  const c = (windowScenes || []).filter((s) => s && Number.isFinite(s.t) && Number.isFinite(s.score));
  const scene_score_max = c.length ? Math.max(...c.map((s) => s.score)) : null;
  const scene_change_near = sceneMaxima(c, threshold).some((pt) => Math.abs(pt - t) <= nearS);
  return { scene_score_max, scene_change_near };
}

/** Parse silencedetect stderr lines into {start, end, duration?}; an unclosed start gets end: null. */
export function parseSilences(text) {
  const out = [];
  let start = null;
  for (const line of String(text || '').split(/\r?\n/)) {
    const m1 = /silence_start:\s*(-?[\d.]+)/.exec(line);
    if (m1) { start = Number(m1[1]); continue; }
    const m2 = /silence_end:\s*(-?[\d.]+)/.exec(line);
    if (m2) {
      const end = Number(m2[1]);
      const md = /silence_duration:\s*([\d.]+)/.exec(line);
      out.push({ start: start == null ? 0 : start, end, ...(md ? { duration: Number(md[1]) } : {}) });
      start = null;
    }
  }
  if (start != null) out.push({ start, end: null }); // still silent at EOF
  return out;
}

/** Parse loudnorm print_format=json output (the trailing JSON block on stderr). */
export function parseLoudnormJson(text) {
  const s = String(text || '');
  const i = s.lastIndexOf('{');
  const j = i >= 0 ? s.indexOf('}', i) : -1;
  if (i < 0 || j < 0) return null;
  let o = null;
  try { o = JSON.parse(s.slice(i, j + 1)); } catch { return null; }
  const num = (v) => { const n = Number(v); return Number.isFinite(n) ? n : null; };
  const I = o.input_i != null ? num(o.input_i) : null;
  if (I == null) return null;
  return {
    I, TP: o.input_tp != null ? num(o.input_tp) : null,
    LRA: o.input_lra != null ? num(o.input_lra) : null,
    threshold: o.input_thresh != null ? num(o.input_thresh) : null,
  };
}

/** Parse an ebur128 summary (fallback when loudnorm JSON does not parse). */
export function parseEbur128(text) {
  const s = String(text || '');
  const mi = /I:\s*(-?\d+(?:\.\d+)?)\s*LUFS/.exec(s);
  if (!mi) return null;
  const mp = /Peak:\s*(-?\d+(?:\.\d+)?)\s*dBFS/.exec(s);
  return { I: Number(mi[1]), TP: mp ? Number(mp[1]) : null, LRA: null, threshold: null };
}

/** Parse ffprobe default text output of -show_packets -show_entries packet=pts_time,flags; keep keyframes (flags contain K). Timestamps are rounded UP to the next ms so a copy-mode -ss at the reported time can never land before the keyframe (which would snap back a whole GOP). */
export function parseKeyframes(text) {
  const out = [];
  let pts = null;
  for (const raw of String(text || '').split(/\r?\n/)) {
    const line = raw.trim();
    const p = /^pts_time=(-?[\d.]+|N\/A)/.exec(line);
    if (p) { pts = p[1] === 'N/A' ? null : Number(p[1]); continue; }
    const f = /^flags=(\S*)/.exec(line);
    if (f) { if (f[1].includes('K') && pts != null) out.push(Math.ceil(pts * 1000) / 1000); pts = null; }
  }
  return out;
}

/** Latest keyframe timestamp at or before t (a copy-mode -ss snaps to it); null when unknown. */
export function keyframeAtOrBefore(keyframes, t) {
  let best = null;
  for (const k of keyframes || []) if (Number.isFinite(k) && k <= t + 1e-6 && (best == null || k > best)) best = k;
  return best;
}

/** The keyframes BRACKETING t: { before: latest <= t, after: earliest >= t } — nulls when
 * unknown. Feeds cut-report's nearest_keyframes (what the re-encode path snapped past). */
export function bracketKeyframes(keyframes, t) {
  let before = null;
  let after = null;
  for (const k of keyframes || []) {
    if (!Number.isFinite(k)) continue;
    if (k <= t + 1e-6 && (before == null || k > before)) before = k;
    if (k >= t - 1e-6 && (after == null || k < after)) after = k;
  }
  return { before, after };
}

/** Parse volumedetect stderr: { mean, max } in dBFS (either null when absent). Digital
 * silence reports as about -91 dB — used by `tighten` (threshold suggestion) and `check`
 * (silent-audio row). */
export function parseVolumedetect(text) {
  const s = String(text || '');
  const mm = /mean_volume:\s*(-?[\d.]+)\s*dB/.exec(s);
  const xm = /max_volume:\s*(-?[\d.]+)\s*dB/.exec(s);
  if (!mm && !xm) return null;
  const n = (m) => (m ? Number(m[1]) : null);
  return { mean: n(mm), max: n(xm) };
}

/** Max volume in dBFS via volumedetect — null when the file has no readable audio. */
async function measureMaxVolume(file) {
  try {
    const rv = await runFf('ffmpeg', ['-i', file, '-vn', '-af', 'volumedetect', '-f', 'null', '-']);
    if (rv.code !== 0) return null;
    const vol = parseVolumedetect(rv.stderr);
    return vol ? vol.max : null;
  } catch { return null; }
}

// ---------------------------------------------------------------- segments builder (pure)

/**
 * Build candidate segments from a probe. Boundaries = union of scene_changes and silence
 * ENDS (natural cut points: breath/sentence boundaries + hard scene changes), plus 0 and
 * duration. From each boundary, greedily take the FURTHEST boundary-delimited segment that
 * fits [min, max]; a video shorter than max is itself one candidate. Ranked by
 * scene density x loudness proximity (loudness is the whole-file measurement, so density
 * drives the ranking), capped at `count`; ids seg_001.. in ranked order.
 */
export function buildSegments(probeData, { min = 15, max = 90, count = 10 } = {}) {
  const eps = 0.05;
  const duration = Number(probeData && probeData.duration) || 0;
  if (!(duration > 0)) return { segments: [], notes: ['probe has no duration — cannot build segments'] };
  const inRange = (t) => Number.isFinite(t) && t > eps && t < duration - eps;
  const sceneChanges = (Array.isArray(probeData.scene_changes) ? probeData.scene_changes : []).map(Number).filter(inRange);
  const silenceEnds = (Array.isArray(probeData.silences) ? probeData.silences : []).map((s) => (s ? Number(s.end) : NaN)).filter(inRange);
  const silenceStarts = (Array.isArray(probeData.silences) ? probeData.silences : []).map((s) => (s ? Number(s.start) : NaN)).filter(inRange);
  const sorted = [...new Set([0, duration, ...sceneChanges, ...silenceEnds].map((t) => +t.toFixed(3)))].sort((a, b) => a - b);
  const bounds = [];
  for (const b of sorted) if (!bounds.length || b - bounds[bounds.length - 1] > eps) bounds.push(b);
  const thrRaw = Number(probeData && probeData.scene_threshold);
  const thr = Number.isFinite(thrRaw) && thrRaw > 0 ? thrRaw : SCENE_THRESHOLD;
  const scenesT = (Array.isArray(probeData.scenes) ? probeData.scenes : [])
    .map((s) => (s && Number.isFinite(Number(s.t)) && Number.isFinite(Number(s.score)) && s.score >= thr ? Number(s.t) : null))
    .filter((t) => t != null);
  const loud = probeData && probeData.loudness ? Number(probeData.loudness.I) : NaN;
  const loudProx = Number.isFinite(loud) ? 1 / (1 + Math.abs(loud - LOUDNORM_TARGET.I) / 10) : 1;
  const silenceEdges = [...silenceEnds, ...silenceStarts];
  const nearSilenceEdge = (x) => silenceEdges.some((e) => Math.abs(e - x) <= 0.75);
  const seen = new Set();
  const mk = (start, end) => {
    const key = `${start.toFixed(3)}|${end.toFixed(3)}`;
    if (seen.has(key)) return null;
    seen.add(key);
    const dur = +(end - start).toFixed(3);
    const density = dur > 0 ? scenesT.filter((t) => t >= start && t < end).length / dur : 0;
    return {
      start: +start.toFixed(3), end: +end.toFixed(3), duration: dur,
      score: +(density * loudProx).toFixed(4),
      signals: {
        scenes: sceneChanges.filter((t) => t > start + eps && t < end - eps).length,
        silence_cut: nearSilenceEdge(start) || nearSilenceEdge(end),
      },
    };
  };
  const candidates = [];
  for (let i = 0; i < bounds.length; i++) {
    const s = bounds[i];
    if (s >= duration - eps) continue;
    let bestEnd = null;
    for (let j = i + 1; j < bounds.length; j++) {
      const e = bounds[j];
      if (e - s > max + eps) break;
      if (e - s >= min - eps) bestEnd = e;
    }
    if (bestEnd != null) { const c = mk(s, bestEnd); if (c) candidates.push(c); }
  }
  if (duration <= max + eps) { const c = mk(0, duration); if (c) candidates.push(c); } // whole video fits in max
  candidates.sort((a, b) => b.score - a.score);
  const ranked = candidates.slice(0, Math.max(1, count))
    .map((c, i) => ({ id: `seg_${String(i + 1).padStart(3, '0')}`, rank: i + 1, start: c.start, end: c.end, duration: c.duration, score: c.score, signals: c.signals }));
  return { segments: ranked };
}

/**
 * N equal mechanical segments over [0, duration] — the honest fallback (--even-split) when
 * no content-aware candidate exists. Each is flagged mechanical: true so downstream steps
 * (and humans) know these are equal divisions, not scene/silence-driven picks.
 */
export function evenSplitSegments(duration, n, { sceneChanges = [], silences = [] } = {}) {
  const eps = 0.05;
  const N = Math.max(1, Math.floor(Number(n) || 1));
  const d = Number(duration) || 0;
  const sceneT = (sceneChanges || []).map(Number).filter((t) => Number.isFinite(t));
  const edges = [];
  for (const s of silences || []) {
    if (!s) continue;
    if (Number.isFinite(Number(s.end))) edges.push(Number(s.end));
    if (Number.isFinite(Number(s.start))) edges.push(Number(s.start));
  }
  const out = [];
  for (let i = 0; i < N; i++) {
    const start = +((d * i) / N).toFixed(3);
    const end = +((d * (i + 1)) / N).toFixed(3);
    out.push({
      start, end, duration: +(end - start).toFixed(3), mechanical: true,
      signals: {
        scenes: sceneT.filter((t) => t > start + eps && t < end - eps).length,
        silence_cut: edges.some((e) => Math.abs(e - start) <= 0.75 || Math.abs(e - end) <= 0.75),
      },
    });
  }
  return out;
}

// ---------------------------------------------------------------- cut / export helpers (pure)

/** Compare an output clip's real duration against the requested one. Tolerance is in seconds. */
export function classifyDuration(actualS, requestedS, tolerance = 0.5) {
  const a = Number(actualS); const r = Number(requestedS);
  if (!Number.isFinite(a) || !Number.isFinite(r)) return { error_ms: null, within: false };
  const err = Math.abs(a - r);
  return { error_ms: Math.round(err * 1000), within: err <= tolerance };
}

export function sanitizeSlug(name) {
  const s = String(name || '').replace(/\.[A-Za-z0-9]+$/, '').replace(/[^A-Za-z0-9._-]+/g, '-').replace(/^[-.]+/, '');
  return s || 'clip';
}

export function exportName(slug, platform, variant) {
  return `${sanitizeSlug(slug)}_${platform}_${variant}.mp4`;
}

/** Validate clips.json. `sourceDuration` (seconds, when known) adds an end-beyond-source
 * warning. Returns { errors, warnings } (never throws). Unknown platform ids are an OPEN
 * LIST: they map to the generic creator profile with a warning, not an error. */
export function validatePlan(plan, sourceDuration = null) {
  const errors = [];
  const warnings = [];
  if (!plan || typeof plan !== 'object' || Array.isArray(plan) || !Array.isArray(plan.clips) || !plan.clips.length) {
    return { errors: ['needs a non-empty "clips" array — see "clipcut.mjs plan" for the schema'], warnings };
  }
  const seenSlugs = new Set();
  const srcDur = Number(sourceDuration);
  plan.clips.forEach((c, i) => {
    const p = `clips[${i}]`;
    if (!c || typeof c !== 'object') { errors.push(`${p} must be an object`); return; }
    if (typeof c.slug !== 'string' || !/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(c.slug)) errors.push(`${p}.slug must be a filename-safe string ([A-Za-z0-9._-], not starting with . or -)`);
    else if (seenSlugs.has(c.slug)) errors.push(`${p}.slug "${c.slug}" is duplicated — slugs must be unique`);
    else seenSlugs.add(c.slug);
    const s = Number(c.start); const e = Number(c.end);
    if (!Number.isFinite(s) || s < 0) errors.push(`${p}.start must be a number >= 0`);
    if (!Number.isFinite(e) || e < 0) errors.push(`${p}.end must be a number >= 0`);
    if (Number.isFinite(s) && Number.isFinite(e) && e <= s) errors.push(`${p}.end must be greater than ${p}.start`);
    if (Number.isFinite(s) && Number.isFinite(e) && e > s) {
      const d = e - s;
      if (d < 5 || d > 600) warnings.push(`${p} "${c.slug}" duration ${fmt(d)}s is outside the 5-600s comfort range`);
    }
    if (Number.isFinite(e) && Number.isFinite(srcDur) && srcDur > 0 && e > srcDur) warnings.push(`${p} "${c.slug}" end ${fmt(e)}s is beyond the source duration ${fmt(srcDur)}s`);
    if (c.variants != null && (!Array.isArray(c.variants) || !c.variants.length || c.variants.some((v) => !VARIANTS.includes(v)))) errors.push(`${p}.variants must be an array of ${VARIANTS.join('|')}`);
    if (c.platforms != null && !Array.isArray(c.platforms)) errors.push(`${p}.platforms must be an array of platform ids`);
    else if (Array.isArray(c.platforms)) {
      if (!c.platforms.length) errors.push(`${p}.platforms must be a non-empty array of platform ids`);
      else for (const pl of c.platforms) if (!PLATFORMS.includes(pl)) warnings.push(`${p}: mapping unknown platform '${pl}' to the generic creator profile`);
    }
  });
  return { errors, warnings };
}

/** Per-clip durations + their total, for plan printing (null = structurally invalid clip). */
export function planDurations(clips) {
  const durations = (clips || []).map((c) => {
    const s = Number(c && c.start); const e = Number(c && c.end);
    return Number.isFinite(s) && Number.isFinite(e) && e > s ? +(e - s).toFixed(3) : null;
  });
  const total = +durations.filter((d) => d != null).reduce((a, b) => a + b, 0).toFixed(3);
  return { durations, total };
}

// ---------------------------------------------------------------- platform specs (single source of truth)

/** Universal container baseline every platform in the table shares (synthesis of the
 * compiled research): H.264 video in yuv420p, AAC audio (48 kHz recommended), MP4 with
 * the moov box at the front (faststart), even (divisible-by-2) dimensions. */
export const PLATFORM_CODEC = { video: 'h264', pixFmt: 'yuv420p', audio: 'aac', sampleRateRecHz: 48000, faststart: true };

/**
 * PLATFORM_SPECS is the SINGLE SOURCE OF TRUTH for per-platform facts. Both the export
 * warnings (platformWarnings) and the `check` subcommand (buildCheckRows) read this
 * table — never copy a number or a hedge out of it into other code. Duration entries
 * carry:
 *   cap              — the `check` FAIL threshold in seconds (null = no practical cap)
 *   mark             — honesty mark: 'verified' | 'community' | 'guidance'
 *   warnFrom / warnInclusive / warnText — the export-warning threshold + exact hedged
 *                      wording (verified caps stated as fact, community-reported
 *                      limits hedged as unverified; tiktok only warns from 570s — the
 *                      3-min figure for it was never verified, standard uploads allow
 *                      up to ~10 min).
 * Aspects are matched with a 0.02 ratio tolerance (same as platformWarnings).
 */
export const PLATFORM_SPECS = {
  youtube: {
    aspects: { accepted: [16 / 9, 1, 9 / 16], vertical: false },
    duration: { cap: null, mark: 'verified', note: '256 GB / 12 h account cap (verified) — no practical limit for clip work' },
    sizeCapBytes: null,
  },
  shorts: {
    aspects: { accepted: [9 / 16], vertical: true },
    duration: {
      cap: 180, mark: 'verified', warnFrom: 180, warnInclusive: false,
      warnText: (d) => `duration ${fmt(d)}s exceeds the 3-minute YouTube Shorts cap (verified)`,
    },
    resolution: { maxShortSide: 1080, mark: 'verified' },
    sizeCapBytes: null,
  },
  tiktok: {
    aspects: { accepted: [9 / 16], vertical: true },
    duration: {
      cap: 600, mark: 'community', warnFrom: 570, warnInclusive: true,
      warnText: (d) => `duration ${fmt(d)}s may exceed community-reported TikTok upload limits (unverified; standard uploads allow up to ~10 min)`,
    },
    resolution: { maxShortSide: 1080, mark: 'community', note: 'informational: 4K uploads get compressed to 1080p (community-reported); 1080p recommended' },
    sizeCapBytes: null,
  },
  reels: {
    aspects: { accepted: [9 / 16], vertical: true },
    duration: {
      cap: 180, mark: 'community', warnFrom: 180, warnInclusive: false,
      warnText: (d) => `duration ${fmt(d)}s may exceed the community-reported 3-minute Reels limit (unverified)`,
    },
    sizeCapBytes: 4 * 1024 * 1024 * 1024, sizeMark: 'community',
  },
  x: {
    aspects: { accepted: [16 / 9, 1, 9 / 16], vertical: false },
    duration: {
      cap: 140, mark: 'community', warnFrom: 140, warnInclusive: false,
      warnText: (d) => `duration ${fmt(d)}s may exceed the community-reported 140s X free-tier limit (unverified; Premium allows up to 4h)`,
    },
    resolution: { maxShortSide: 1080, mark: 'community' },
    sizeCapBytes: 512 * 1024 * 1024, sizeMark: 'community',
  },
  creator: {
    aspects: { accepted: [9 / 16], vertical: true },
    duration: {
      cap: 90, mark: 'guidance', warnFrom: 90, warnInclusive: false,
      warnText: (d) => `duration ${fmt(d)}s exceeds the 60–90s generic creator-platform guidance`,
    },
    sizeCapBytes: null,
  },
};

/** Platform spec warnings from the shared table (duration caps, vertical aspect). */
export function platformWarnings(platform, durationS, dims = {}, variant = 'original') {
  const w = [];
  const d = Number(durationS);
  if (!PLATFORMS.includes(platform)) return w;
  const spec = PLATFORM_SPECS[platform] || {};
  const rule = spec.duration || {};
  if (rule.warnText && Number.isFinite(d) && (rule.warnInclusive ? d >= rule.warnFrom : d > rule.warnFrom)) w.push(rule.warnText(d));
  if (spec.aspects && spec.aspects.vertical) {
    const wd = Number(dims.width); const ht = Number(dims.height);
    if (Number.isFinite(wd) && Number.isFinite(ht) && wd > 0 && ht > 0) {
      const ar = wd / ht;
      if (Math.abs(ar - 9 / 16) > 0.02) w.push(`output is ${wd}x${ht} (~${ar.toFixed(3)}:1), not 9:16 — ${platform} expects vertical 1080x1920 (use --variant 9x16-crop or 9x16-blur)`);
    }
  }
  return w;
}

// ---------------------------------------------------------------- tighten / check (pure)

/**
 * Keep-span builder for `tighten` (silence removal), pure. Each silence [start, end]
 * (end null = silent to EOF) becomes a removal [start+margin, end-margin]: `margin`
 * seconds of silence stay attached to the speech on each side so the joins sound
 * natural. A silence fully eaten by its margins removes nothing. Removals are merged,
 * then kept spans shorter than `minKeep` are dropped (swallowed by their neighboring
 * removals). Returns { keep: [[a,b],...] ascending, cuts: removal count,
 * removedS: seconds removed } over [0, duration].
 */
export function buildKeepSpans(duration, silences, { margin = TIGHTEN_DEFAULTS.marginS, minKeep = TIGHTEN_DEFAULTS.minKeepS } = {}) {
  const dur = Number(duration) || 0;
  const clamp = (x) => Math.max(0, Math.min(dur, x));
  const removals = [];
  for (const s of silences || []) {
    if (!s) continue;
    const st = Number(s.start);
    const en = s.end == null ? dur : Number(s.end);
    if (!Number.isFinite(st) || !Number.isFinite(en) || en <= st) continue;
    const a = clamp(st + margin);
    const b = clamp(en - margin);
    if (b > a) removals.push([a, b]);
  }
  removals.sort((x, y) => x[0] - y[0] || x[1] - y[1]);
  const merged = [];
  for (const r of removals) {
    if (merged.length && r[0] <= merged[merged.length - 1][1]) merged[merged.length - 1][1] = Math.max(merged[merged.length - 1][1], r[1]);
    else merged.push([r[0], r[1]]);
  }
  let keep = [];
  let t = 0;
  for (const [a, b] of merged) { if (a > t) keep.push([t, a]); t = Math.max(t, b); }
  if (t < dur) keep.push([t, dur]);
  keep = keep.filter((k) => k[1] - k[0] >= minKeep);
  const keptS = keep.reduce((a, k) => a + (k[1] - k[0]), 0);
  const cuts = Math.max(0, keep.length - 1)
    + (keep.length && keep[0][0] > 1e-9 ? 1 : 0)
    + (keep.length && keep[keep.length - 1][1] < dur - 1e-9 ? 1 : 0);
  return { keep, cuts, removedS: +Math.max(0, dur - keptS).toFixed(3) };
}

/** Suggested silencedetect threshold when no silence was found: track mean level + 6 dB,
 * capped at -5 dB (never suggest anything near full scale). null when the mean is unknown. */
export function suggestThreshold(meanDb) {
  if (meanDb == null) return null;
  const m = Number(meanDb);
  if (!Number.isFinite(m)) return null;
  return +Math.min(m + 6, -5).toFixed(1);
}

/**
 * Build the `check` compliance rows from measured facts (pure — feeds the report and the
 * selftests). Null facts fields are UNMEASURABLE: they become WARN "could not measure",
 * never PASS. Row kinds: "judgement" (duration, aspect, loudness — platform-dependent
 * taste) and "format" (objective container facts). Judgement rows FAIL only with a
 * --platform; without one they are evaluated against the generic creator profile (the
 * open-list default) and downgrade to WARN. Format rows enforce in both modes.
 * Each non-PASS row carries a plain `reason` and, when a real fix exists, a `fix`
 * naming the exact clipcut command.
 */
export function buildCheckRows(facts, { platform = null } = {}) {
  const f = facts || {};
  const spec = platform && PLATFORM_SPECS[platform] ? PLATFORM_SPECS[platform] : null;
  const eff = spec || PLATFORM_SPECS.creator; // open-list default: generic creator profile
  const downgrade = !platform;                // judgement FAIL -> WARN without --platform
  const fin = (x) => { const n = x == null ? NaN : Number(x); return Number.isFinite(n) ? n : null; }; // Number(null) is 0 — never let null look measured
  const rows = [];
  const add = (check, kind, status, extra = {}) => {
    const row = { check, kind, status };
    if (extra.reason) row.reason = extra.reason;
    if (extra.fix) row.fix = extra.fix;
    if (extra.note) row.note = extra.note;
    rows.push(row);
  };
  const unmeasurable = (check, kind, why) => add(check, kind, 'WARN', { reason: `could not measure (${why})` });
  const judge = (check, status, extra = {}) => add(check, 'judgement', downgrade && status === 'FAIL' ? 'WARN' : status, extra);
  const fixExport = (variant, tail = '') => `clipcut export ${f.file || '<file>'} --platform ${platform || 'creator'} --variant ${variant}${tail}`;
  const arName = (r) => (Math.abs(r - 9 / 16) < 1e-9 ? '9:16' : Math.abs(r - 16 / 9) < 1e-9 ? '16:9' : '1:1');

  // duration — judgement.
  if (fin(f.duration) == null || !(fin(f.duration) > 0)) {
    unmeasurable('duration', 'judgement', 'ffprobe reported no duration');
  } else {
    const d = fin(f.duration);
    const rule = eff.duration || {};
    const over = rule.cap != null && d > rule.cap;
    const inWarnZone = !over && rule.warnFrom != null && rule.cap != null && rule.warnFrom < rule.cap
      && (rule.warnInclusive ? d >= rule.warnFrom : d > rule.warnFrom);
    // Only VERIFIED caps hard-FAIL: a cap the platform table itself marks
    // community/guidance is reported loudly but never blocks delivery on its own.
    if (over) judge('duration', rule.mark === 'verified' ? 'FAIL' : 'WARN', {
      reason: rule.warnText(d),
      note: `${fmt(d)}s vs the ${rule.cap}s ${platform || 'creator'} cap (${rule.mark}${rule.mark === 'verified' ? '' : ' — reported, not enforced'})`,
      fix: `clipcut cut <source> --plan clips.json (shorten this clip's end — duration is set by the plan)`,
    });
    else if (inWarnZone) judge('duration', 'WARN', { reason: rule.warnText(d), note: `${fmt(d)}s vs the conservative ${rule.warnFrom}s warn threshold` });
    else judge('duration', 'PASS', { note: `${fmt(d)}s${rule.cap != null ? ` (cap ${rule.cap}s, ${rule.mark})` : rule.note ? ` — ${rule.note}` : ''}` });
  }

  // aspect — judgement. width/height are DISPLAY dims (rotation metadata already
  // applied by the probe), so a rotated file is judged by what it shows, not by its
  // coded storage order; a swap is noted so the row explains itself.
  if (fin(f.width) == null || fin(f.height) == null || !(fin(f.width) > 0)) {
    unmeasurable('aspect', 'judgement', 'ffprobe reported no dimensions');
  } else {
    const wd = fin(f.width); const ht = fin(f.height);
    const ar = wd / ht;
    const want = (eff.aspects.accepted || []).map(arName).join(' or ');
    const rotDeg = fin(f.rotation);
    const rotNote = rotDeg != null && Math.abs(rotDeg) % 180 === 90
      ? ` — displays ${wd}x${ht} after rotation metadata (${fmt(rotDeg)}deg)`
      : '';
    if ((eff.aspects.accepted || []).some((r) => Math.abs(ar - r) <= 0.02)) judge('aspect', 'PASS', { note: `${wd}x${ht} (~${ar.toFixed(3)}:1) matches ${want}${rotNote}` });
    else judge('aspect', 'FAIL', {
      reason: `output is ${wd}x${ht} (~${ar.toFixed(3)}:1), not ${want}${platform ? ` — ${platform} expects ${eff.aspects.vertical ? 'vertical 9:16 1080x1920' : want}` : ' — the generic creator profile expects vertical 9:16'}${rotNote}`,
      fix: eff.aspects.vertical ? fixExport('9x16-crop') : undefined,
    });
  }

  // resolution — format: divisible-by-2 (H.264 4:2:0 needs even dimensions).
  if (fin(f.width) == null || fin(f.height) == null || !(fin(f.width) > 0)) unmeasurable('resolution', 'format', 'ffprobe reported no dimensions');
  else if (f.width % 2 !== 0 || f.height % 2 !== 0) add('resolution', 'format', 'FAIL', { reason: `dimensions ${f.width}x${f.height} are not divisible by 2 — H.264 4:2:0 encoding needs even numbers`, fix: fixExport('original') });
  else add('resolution', 'format', 'PASS', { note: `${f.width}x${f.height}, both divisible by 2` });

  // resolution cap — judgement, informational WARN only (never a hard gate): the
  // short side exceeds the max the platform's specs row itself marks.
  if (eff.resolution && eff.resolution.maxShortSide != null && fin(f.width) != null && fin(f.height) != null && fin(f.width) > 0) {
    const shortSide = Math.min(f.width, f.height);
    const cap = eff.resolution.maxShortSide;
    if (shortSide > cap) judge('resolution_cap', 'WARN', {
      reason: `short side ${shortSide}px exceeds the ${cap}px max the ${platform || 'creator'} row marks (${eff.resolution.mark}${eff.resolution.mark === 'verified' ? '' : '-reported, unverified'})${eff.resolution.note ? ` — ${eff.resolution.note}` : ''}`,
      note: 'informational — platforms accept or recompress larger files; no hard gate',
    });
  }

  // fps + VFR/CFR — format (VFR is a compatibility hazard, not a hard reject).
  if (fin(f.fps) == null || !(fin(f.fps) > 0)) unmeasurable('fps', 'format', 'ffprobe reported no frame rate');
  else if (f.vfr) add('fps', 'format', 'WARN', { reason: `variable frame rate suspected (r_frame_rate vs avg_frame_rate differ by > 0.5 fps around ${fmt(f.fps)}fps) — players may judder; a re-encode makes it CFR`, fix: `clipcut cut <source> --plan clips.json --mode accurate, or ${fixExport('9x16-crop')}` });
  else add('fps', 'format', 'PASS', { note: `${fmt(f.fps)}fps, constant (CFR)` });

  // codec / pix_fmt — format: the shared H.264 + yuv420p baseline.
  if (!f.videoCodec) unmeasurable('codec', 'format', 'ffprobe reported no video codec');
  else if (f.videoCodec !== PLATFORM_CODEC.video) add('codec', 'format', 'FAIL', { reason: `video codec ${f.videoCodec} — the platform baseline is ${PLATFORM_CODEC.video} (H.264)`, fix: fixExport('original') });
  else add('codec', 'format', 'PASS', { note: `${PLATFORM_CODEC.video} (${f.videoCodec})` });

  if (!f.pixFmt) unmeasurable('pix_fmt', 'format', 'ffprobe reported no pixel format');
  else if (f.pixFmt !== PLATFORM_CODEC.pixFmt) add('pix_fmt', 'format', 'FAIL', { reason: `pixel format ${f.pixFmt} — the platform baseline is ${PLATFORM_CODEC.pixFmt} (most web/mobile players show nothing else)`, fix: fixExport('original') });
  else add('pix_fmt', 'format', 'PASS', { note: `${PLATFORM_CODEC.pixFmt}` });

  // audio presence / codec / sample rate — format. No audio stream = unmeasurable WARN
  // (platforms accept silent video; it is not a compliance failure).
  if (!f.hasAudio) {
    unmeasurable('audio', 'format', 'no audio stream');
    unmeasurable('audio_sample_rate', 'format', 'no audio stream');
    unmeasurable('loudness', 'judgement', 'no audio stream');
    unmeasurable('silent_audio', 'format', 'no audio stream');
  } else {
    if (!f.audioCodec) unmeasurable('audio', 'format', 'audio stream present but codec not reported');
    else if (f.audioCodec !== PLATFORM_CODEC.audio) add('audio', 'format', 'WARN', { reason: `audio codec ${f.audioCodec}, not ${PLATFORM_CODEC.audio} (AAC) — re-encoding the audio is the safe route`, fix: fixExport('original', ' --loudnorm') });
    else add('audio', 'format', 'PASS', { note: `${PLATFORM_CODEC.audio} audio present` });
    if (fin(f.audioSampleRate) == null) unmeasurable('audio_sample_rate', 'format', 'sample rate not reported');
    else if (f.audioSampleRate === PLATFORM_CODEC.sampleRateRecHz) add('audio_sample_rate', 'format', 'PASS', { note: `${f.audioSampleRate} Hz (recommended)` });
    else if (f.audioSampleRate === 44100) add('audio_sample_rate', 'format', 'PASS', { note: '44100 Hz (widely accepted; 48000 Hz is the recommendation)' });
    else add('audio_sample_rate', 'format', 'WARN', { reason: `audio sample rate ${f.audioSampleRate} Hz is unusual — ${PLATFORM_CODEC.sampleRateRecHz} Hz recommended` });

    // loudness — judgement, measure-only (no platform documents -14 LUFS; it is a web norm).
    // FAIL only for clipping (TP > 0 dBTP) or an over-loud master (I above ~-2 LUFS);
    // the QUIET side is a WARN — no platform documents -14, and platforms turn loud
    // clips down, never up, so a quiet master is taste, not a defect.
    if (!f.loudness || !Number.isFinite(Number(f.loudness.I))) {
      unmeasurable('loudness', 'judgement', 'loudness measurement did not parse (silent or unreadable audio)');
    } else {
      const I = Number(f.loudness.I);
      const TP = f.loudness.TP != null && Number.isFinite(Number(f.loudness.TP)) ? Number(f.loudness.TP) : null;
      const devI = Math.abs(I - LOUDNORM_TARGET.I);
      const clipping = TP != null && TP > 0;
      const overLoud = I > -2;
      const quiet = I < LOUDNORM_TARGET.I - 6;
      const note = `I=${I} LUFS${TP != null ? `, true peak=${TP} dBTP` : ''} vs the -14 LUFS / -1.5 dBTP web target (measure-only)`;
      if (!clipping && !overLoud && devI <= 6 && (TP == null || TP <= -1)) judge('loudness', 'PASS', { note });
      else if (clipping || overLoud) {
        const why = [];
        if (overLoud) why.push(`integrated loudness ${I} LUFS is above -2 LUFS (over-loud master)`);
        if (clipping) why.push(`true peak ${TP} dBTP is above 0 dBTP (clipping)`);
        judge('loudness', 'FAIL', { reason: `${why.join('; ')} (measure-only judgement)`, fix: fixExport('original', ' --loudnorm') });
      } else {
        // WARN zone: quiet master, or a mild peak/loudness deviation — never a hard gate.
        let reason;
        if (quiet) reason = `integrated loudness ${I} LUFS is ${fmt(LOUDNORM_TARGET.I - I)} LU below -14 LUFS — no platform documents -14 (community norm); quiet master, consider export --loudnorm`;
        else if (TP != null && TP > -1) reason = `true peak ${TP} dBTP exceeds -1.5 dBTP (measure-only judgement)`;
        else reason = `integrated loudness ${I} LUFS is ${fmt(devI)} LU from -14 LUFS (measure-only judgement)`;
        judge('loudness', 'WARN', { reason, note, fix: fixExport('original', ' --loudnorm') });
      }
    }

    // silent audio — format: a dead track is a defect, not a style choice.
    if (f.silentAudio == null) unmeasurable('silent_audio', 'format', 'volumedetect did not report levels');
    else if (f.silentAudio) add('silent_audio', 'format', 'FAIL', { reason: `audio measures as digital silence (max level <= ${SILENT_MAX_DB} dBFS) — the audio track is dead` });
    else add('silent_audio', 'format', 'PASS', { note: `max level ${f.audioMaxDb != null ? `${f.audioMaxDb} dBFS` : `above ${SILENT_MAX_DB} dBFS`}` });
  }

  // faststart — format: moov-box walk.
  if (f.faststart === true) add('faststart', 'format', 'PASS', { note: 'moov box before mdat (faststart)' });
  else if (f.faststart === false) add('faststart', 'format', 'FAIL', { reason: 'moov box is not at the front (no faststart) — players must buffer the whole file before playback starts', fix: fixExport('original') });
  else unmeasurable('faststart', 'format', 'not an MP4/MOV-family container (the moov-box walk does not apply)');

  // size — format, only where the table carries a cap (community-reported): WARN, not FAIL.
  // A cap with an unmeasurable size is a WARN like every other unmeasurable fact —
  // never a silently absent row.
  if (eff.sizeCapBytes != null) {
    if (fin(f.sizeBytes) == null) unmeasurable('size', 'format', 'size unknown');
    else {
      const mib = f.sizeBytes / 1024 / 1024;
      const capMib = eff.sizeCapBytes / 1024 / 1024;
      if (f.sizeBytes > eff.sizeCapBytes) add('size', 'format', 'WARN', { reason: `file is ${mib.toFixed(1)} MiB, over the ~${capMib.toFixed(0)} MiB ${platform || 'creator'} cap (${eff.sizeMark}-reported)` });
      else add('size', 'format', 'PASS', { note: `${mib.toFixed(1)} MiB (cap ~${capMib.toFixed(0)} MiB, ${eff.sizeMark}-reported)` });
    }
  }
  return rows;
}

/** True when the mp4 top-level box order is moov-before-mdat (faststart). */
export function hasFaststart(file) {
  let fd;
  try { fd = fs.openSync(file, 'r'); } catch { return false; }
  try {
    let off = 0;
    const hdr = Buffer.alloc(8);
    for (let i = 0; i < 16; i++) {
      const { bytesRead } = fs.readSync(fd, hdr, 0, 8, off);
      if (bytesRead < 8) return false;
      const size = hdr.readUInt32BE(0);
      const type = hdr.subarray(4, 8).toString('latin1');
      if (type === 'moov') return true;
      if (type === 'mdat') return false;
      if (size < 8) return false;
      off += size;
    }
    return false;
  } finally { fs.closeSync(fd); }
}

const evenDims = (w, h) => Number.isFinite(w) && Number.isFinite(h) && w % 2 === 0 && h % 2 === 0;

/**
 * Bounded 9:16 crop window for ANY source aspect — the math behind
 * crop='min(iw,ih*9/16)':'min(ih,iw*16/9)': the window never exceeds the frame in either
 * dimension, so scale=1080:1920 always fills. Portrait/taller-than-9:16 sources crop width
 * from iw (the old crop=ih*9/16:ih asked for a WIDER window than the frame and failed).
 */
export function cropTarget(w, h) {
  const wd = Number(w); const ht = Number(h);
  if (!Number.isFinite(wd) || !Number.isFinite(ht) || wd <= 0 || ht <= 0) return { width: null, height: null };
  return { width: Math.min(wd, (ht * 9) / 16), height: Math.min(ht, (wd * 16) / 9) };
}

/**
 * Validated crop anchor: a fraction in [0,1] of the leftover region (0 = flush with
 * the left/top edge, 1 = flush with the right/bottom edge, 0.5 = centered). Clean
 * UserError on anything else — mirrors numFlag's error shape.
 */
export function cropAnchor(raw, name, dflt = 0.5) {
  if (raw == null || raw === true) return dflt;
  const n = Number(raw);
  if (!Number.isFinite(n) || n < 0 || n > 1) throw new UserError(`--${name} must be a number between 0 and 1 (fraction of the leftover region; 0 = left/top edge, 1 = right/bottom edge). Got: ${raw}`);
  return n;
}

/**
 * The 9x16-crop -vf chain, optionally ANCHORED: the bounded crop window is positioned
 * by crop-x/crop-y fractions of the leftover width/height:
 *   x = (iw - out_w) * ax,  y = (ih - out_h) * ay
 * REGRESSION GUARD (selftested as exact string equality): with both anchors at the
 * 0.5 default the returned string is BYTE-IDENTICAL to the historical center-crop
 * filter — the 2-argument crop — so default runs are provably unchanged. Non-default
 * anchors emit the 4-argument crop with the computed x/y expressions.
 */
export function cropAnchorFilter(ax = 0.5, ay = 0.5) {
  const W = "'min(iw,ih*9/16)'";
  const H = "'min(ih,iw*16/9)'";
  const atDefault = (x) => Number.isFinite(Number(x)) && Math.abs(Number(x) - 0.5) < 1e-9;
  const f = (x) => String(+(+x).toFixed(4));
  if (atDefault(ax) && atDefault(ay)) {
    return `crop=${W}:${H},scale=1080:1920,setsar=1`;
  }
  // 4-argument crop: x/y as a fraction of the leftover region. A default anchor is
  // expressed the same way (fraction 0.5) — (iw-out_w)*0.5 IS the centered position.
  const X = `(iw-min(iw,ih*9/16))*${f(ax)}`;
  const Y = `(ih-min(ih,iw*16/9))*${f(ay)}`;
  return `crop=${W}:${H}:'${X}':'${Y}',scale=1080:1920,setsar=1`;
}

// ---------------------------------------------------------------- Cloudflare API layer

const API_BASE = 'https://api.cloudflare.com/client/v4/accounts';

/** POST endpoint for a FULL model id (@cf/cloudflare/...) — the id goes in verbatim, exactly once. */
export function runUrl(accountId, modelFull) {
  return `${API_BASE}/${accountId}/ai/run/${modelFull}`;
}

let LAST_FETCH_AT = 0; // pacing: >= 300 ms between request starts

/**
 * POST /ai/run/<full model id>. Envelope {success,result,errors}. Retries 429 (except daily
 * quota 3036) and 5xx with backoff; retry-after honored, capped at 60 s. 413 -> e.code=413.
 */
async function postAi(modelFull, body, { gateway } = {}) {
  const c = cfg();
  if (!c.accountId || !c.token) throw new UserError('CLOUDFLARE_ACCOUNT_ID and CLOUDFLARE_API_TOKEN are required (process env, ./.env or ~/.clefcut/.env). Run "clipcut.mjs doctor".');
  const gw = gateway || c.gateway;
  const headers = { Authorization: `Bearer ${c.token}`, 'Content-Type': 'application/json' };
  if (gw) headers['cf-aig-gateway-id'] = gw; // routes the call through an AI Gateway
  const url = runUrl(c.accountId, modelFull);
  const payload = JSON.stringify(body);
  let delay = 1000;
  for (let attempt = 0; ; attempt++) {
    const gap = Date.now() - LAST_FETCH_AT;
    if (gap < PACE_MS) await sleep(PACE_MS - gap);
    const ac = new AbortController();
    const timer = setTimeout(() => ac.abort(), TIMEOUT_MS);
    let res;
    try {
      res = await fetch(url, { method: 'POST', headers, body: payload, signal: ac.signal });
    } catch (e) {
      LAST_FETCH_AT = Date.now();
      clearTimeout(timer);
      if (attempt >= RETRIES) throw new UserError(redact(`network error calling ${modelFull}: ${e.message}`));
      await sleep(delay); delay *= 2; continue;
    }
    LAST_FETCH_AT = Date.now();
    clearTimeout(timer);
    if (res.status === 413) { const e = new Error('request too large'); e.code = 413; throw e; }
    const raw = await res.text();
    let json = null; try { json = JSON.parse(raw); } catch { /* non-json body */ }
    const firstErr = json && Array.isArray(json.errors) && json.errors[0] ? json.errors[0] : null;
    const errCode = firstErr ? Number(firstErr.code) : NaN;
    if (res.status === 429 && errCode === 3036) {
      throw new UserError(redact(`${modelFull}: daily neuron quota exhausted — resets 00:00 UTC (HTTP 429, code 3036). Retrying cannot help; request rejected before processing — nothing was charged.`));
    }
    if ((res.status === 429 || res.status >= 500) && attempt < RETRIES) {
      const ra = Number(res.headers.get('retry-after'));
      await sleep(Number.isFinite(ra) && ra > 0 ? Math.min(ra * 1000, 60_000) : delay);
      delay *= 2; continue;
    }
    if (res.ok && json && json.success) return json.result;
    const msg = json && Array.isArray(json.errors) && json.errors.length ? JSON.stringify(json.errors) : raw.slice(0, 400);
    const again = res.status === 429 || res.status >= 500 ? ` still failing after ${RETRIES + 1} attempts` : '';
    throw new UserError(redact(`${modelFull}${again} (HTTP ${res.status}): ${msg}`));
  }
}

/** Run a body per image batch; on 413 recursively bisect the batch down to 1 image. */
async function runImageBatches(modelFull, makeBody, images, opts, onResult = null) {
  try {
    const result = await postAi(modelFull, makeBody(images), opts);
    if (onResult) onResult(images.length, result);
    return [{ images, result }];
  } catch (e) {
    if (e.code === 413 && images.length > 1) {
      const half = Math.ceil(images.length / 2);
      const a = await runImageBatches(modelFull, makeBody, images.slice(0, half), opts, onResult);
      const b = await runImageBatches(modelFull, makeBody, images.slice(half), opts, onResult);
      return [...a, ...b];
    }
    throw e;
  }
}

/**
 * One request per file batch (413 bisection inside keeps order). `emit(slice, result,
 * isolated)` fires once per actual request with the image files that request covered.
 */
async function requestBatch(modelFull, makeBody, batch, { gateway, isolated = false } = {}, emit) {
  const images = batch.map((f) => toDataUri(f.path));
  let bi = 0;
  await runImageBatches(modelFull, makeBody, images, { gateway }, (count, result) => {
    const slice = batch.slice(bi, bi + count);
    bi += count;
    emit(slice, result, isolated);
  });
}

/** Parse + validate --max-images (>= 1, capped at the API limit); default per command. */
function imageBatchSize(o, dflt) {
  const raw = o['max-images'] != null ? o['max-images'] : dflt;
  const n = Number(raw);
  if (!Number.isFinite(n) || n < 1) throw new UserError(`--max-images must be >= 1. Got: ${raw}`);
  return Math.min(Math.floor(n), MAX_IMAGES);
}

const costEstimate = (model, usage) => (usage.input_tokens * (PRICES[model] ?? 0)) / 1e6;
const usageLine = (model, u) => `usage: ${u.input_tokens} input tokens, ${u.output_tokens} output tokens — cost estimate $${costEstimate(model, u).toFixed(6)} (estimate, ${model} at $${PRICES[model]}/Mtok input, output free)`;

/**
 * Pre-flight cost gate: print the request/cost estimate BEFORE anything is sent; runs over
 * GATE_MAX_IMAGES images require --yes (or CLEFCUT_YES=1). The gate counts IMAGES sent.
 */
function preflightGate(files, dims, { model, size, yes, extraRequests = 0 }) {
  const n = files.length;
  const per = estTokensPerFrame(dims.width, dims.height);
  const requests = Math.ceil(n / Math.max(1, size)) + extraRequests;
  const cost = (n * per * (PRICES[model] ?? 0)) / 1e6;
  console.log(`${n} images → ~${requests} request(s) (batch ≤${size} image(s)) ≈ $${cost.toFixed(4)} input-token estimate at ${model} price (~${per} tokens/image at ${dims.width || '?'}px) (excludes any auto-isolation re-sends)`);
  if (n > GATE_MAX_IMAGES && !yes) {
    throw new UserError(`${n} images is over the ${GATE_MAX_IMAGES}-image comfort limit (estimate above). Pass --yes (or set CLEFCUT_YES=1) to proceed anyway.`);
  }
}

function toDataUri(p) {
  const buf = fs.readFileSync(p);
  if (buf.length > MAX_IMAGE_BYTES) throw new UserError(`${path.basename(p)} is over 4 MiB — regenerate the sheet smaller (or fewer frames per sheet).`);
  return `data:image/png;base64,${buf.toString('base64')}`;
}

// ---------------------------------------------------------------- questions schema (identical to sibling)

export function validateQuestions(spec) {
  const bad = (m) => new UserError(`questions.json invalid: ${m} Schema: {"questions": {"<id>": {"type": "noul"|"choice"|"score", "instructions": "...", "criteria": ...}}, "pass": {"<id>": number in (0,1]}, "escalate_margin": 0.3, "severity": {...}, "escalate_only": [...]}`);
  if (!spec || typeof spec !== 'object' || !spec.questions || !Object.keys(spec.questions).length) throw bad('needs a non-empty "questions" object.');
  if (Object.keys(spec.questions).length > 64) throw bad(`too many questions (${Object.keys(spec.questions).length}) — the API allows at most 64.`);
  for (const [id, q] of Object.entries(spec.questions)) {
    if (!['noul', 'choice', 'score'].includes(q.type)) throw bad(`question "${id}": type must be noul, choice or score.`);
    if (!q.instructions) throw bad(`question "${id}": instructions is required.`);
    if (q.type === 'choice') {
      if (typeof q.criteria !== 'object' || Array.isArray(q.criteria) || !q.criteria) throw bad(`question "${id}": choice needs criteria as an OBJECT of option -> description.`);
      const nOpts = Object.keys(q.criteria).length;
      if (nOpts < 2 || nOpts > 255) throw bad(`question "${id}": choice needs 2-255 options (got ${nOpts}).`);
    }
    if (q.type === 'score') {
      if (!Array.isArray(q.criteria) || q.criteria.length < 2) throw bad(`question "${id}": score needs criteria as an ordered ARRAY (worst last), 2-10 levels.`);
      if (q.criteria.length > 10) throw bad(`question "${id}": score criteria allows at most 10 levels (got ${q.criteria.length}).`);
    }
  }
  const pass = spec.pass && typeof spec.pass === 'object' ? spec.pass : {};
  const esc = new Set(Array.isArray(spec.escalate_only) ? spec.escalate_only : []);
  const missing = Object.keys(spec.questions).filter((id) => {
    const t = pass[id];
    return !(esc.has(id) || (typeof t === 'number' && Number.isFinite(t) && t > 0 && t <= 1));
  });
  if (missing.length) throw new UserError(`questions.json invalid: every question id needs a numeric "pass" in (0,1] or a spot in "escalate_only" — missing for: ${missing.join(', ')}.`);
}

// ---------------------------------------------------------------- local OCR (free)

async function localOcrKind() {
  try { createRequire(path.join(process.cwd(), 'package.json')).resolve('tesseract.js'); return 'tesseract.js'; } catch { /* not installed */ }
  try { if ((await runExe('tesseract', ['--version'])).code === 0) return 'system-tesseract'; } catch { /* not on PATH */ }
  return null;
}

/** OCR a list of images with the chosen local engine; rows keyed by `id`. */
async function ocrImages(kind, files) {
  const rows = [];
  // leptonica (used by both engines) rejects symlinked dirs like /tmp on macOS: pass real paths.
  const realPath = (p) => { try { return fs.realpathSync(p); } catch { return p; } };
  if (kind === 'tesseract.js') {
    const T = createRequire(path.join(process.cwd(), 'package.json'))('tesseract.js');
    const worker = await T.createWorker('eng');
    try {
      for (const f of files) {
        const { data } = await worker.recognize(realPath(f.path));
        rows.push({ segment: f.id, file: f.file, engine: 'tesseract.js', text: (data.text || '').trim(), confidence: typeof data.confidence === 'number' ? data.confidence : null });
      }
    } finally { await worker.terminate(); }
    return rows;
  }
  for (const f of files) {
    const r = await runExe('tesseract', [realPath(f.path), 'stdout', '--psm', '6', 'tsv']);
    if (r.code !== 0) throw new UserError(`tesseract failed on ${f.file}: ${r.stderr.trim().slice(0, 200)}`);
    const cols = r.stdout.toString().split('\n').map((l) => l.split('\t'));
    const words = cols.filter((c) => c.length >= 12 && c[0] === '5' && c[11] && c[11].trim()); // tsv level 5 = word
    const confs = words.map((c) => Number(c[10])).filter((x) => Number.isFinite(x) && x >= 0);
    rows.push({ segment: f.id, file: f.file, engine: 'system-tesseract', text: words.map((c) => c[11].trim()).join(' '), confidence: confs.length ? +(confs.reduce((a, b) => a + b, 0) / confs.length).toFixed(1) : null });
  }
  return rows;
}

// ---------------------------------------------------------------- shared ffmpeg helpers

/** Hidden temp-sibling name for an atomic output: `.<stem>.tmp-<rand><ext>` in the same
 * dir (same filesystem, so renameSync is atomic). The media extension STAYS on the name —
 * ffmpeg picks its muxer from the output extension. */
export function tempSiblingName(name, rand = Math.random().toString(36).slice(2, 10)) {
  const base = path.basename(String(name));
  const ext = path.extname(base);
  const stem = ext ? base.slice(0, -ext.length) : base;
  return `.${stem}.tmp-${rand}${ext}`;
}

/** Matches the temp-sibling names atomicMediaWrite leaves behind on a crash. */
const TEMP_OUTPUT_RE = /^\..+\.tmp-[a-z0-9]+(?:\.[A-Za-z0-9]+)?$/;

/**
 * Atomic media write: `run(tmp)` encodes into a hidden temp sibling, `verify(tmp)`
 * probes it (duration read, faststart box walk, ...) and only then is the temp
 * renameSync'd onto `finalPath`. On ANY failure the temp is removed and a pre-existing
 * final file is left untouched — a failed or truncated encode can never replace good
 * output with a broken file.
 */
async function atomicMediaWrite(finalPath, run, verify) {
  const dir = path.dirname(finalPath);
  fs.mkdirSync(dir, { recursive: true });
  const tmp = path.join(dir, tempSiblingName(finalPath));
  try {
    await run(tmp);
    await verify(tmp);
    fs.renameSync(tmp, finalPath);
  } catch (e) {
    fs.rmSync(tmp, { force: true, recursive: true });
    throw e;
  }
}

/** Managed output dir: every existing entry must be tool-created (isManaged); those are cleared. */
function prepareManagedDir(dir, isManaged, what) {
  if (fs.existsSync(dir)) {
    if (!fs.statSync(dir).isDirectory()) throw new UserError(`output path exists and is not a directory: ${dir}`);
    const entries = fs.readdirSync(dir);
    for (const e of entries) {
      if (!isManaged(e)) throw new UserError(`output dir has unrelated files; choose a fresh --out (found "${e}" in ${dir})`);
    }
    for (const e of entries) fs.rmSync(path.join(dir, e), { force: true, recursive: true });
  }
  fs.mkdirSync(dir, { recursive: true });
  return dir;
}

/**
 * Managed output dir that refuses unrelated files but clears ONLY `removeNames` — other
 * managed files from earlier runs survive, so re-running one clip/slug in the same dir
 * works without destroying its siblings. Stale atomic-write temps (`.name.tmp-<rand>`
 * from a crashed run) are always removed: they are this tool's own litter.
 */
function prepareManagedDirKeep(dir, isManaged, removeNames) {
  if (fs.existsSync(dir)) {
    if (!fs.statSync(dir).isDirectory()) throw new UserError(`output path exists and is not a directory: ${dir}`);
    for (const e of fs.readdirSync(dir)) {
      if (!isManaged(e) && !TEMP_OUTPUT_RE.test(e)) throw new UserError(`output dir has unrelated files; choose a fresh --out (found "${e}" in ${dir})`);
    }
    for (const e of fs.readdirSync(dir)) if (TEMP_OUTPUT_RE.test(e)) fs.rmSync(path.join(dir, e), { force: true });
    for (const n of removeNames) fs.rmSync(path.join(dir, n), { force: true });
  }
  fs.mkdirSync(dir, { recursive: true });
  return dir;
}

/**
 * Contact sheet PNG for [start, end]: `frames` evenly-spaced stills (offset +0.5 cell so
 * cells are cell-midpoints), scale ~480 px wide, tiled in reading order. Manual
 * extract+tile so the cell count is exact regardless of source fps.
 */
async function contactSheet(video, { start, end, frames = 6, outPng, width = 480 }) {
  const dur = Math.max(0, end - start);
  const cols = frames <= 4 ? 2 : 3;
  const rows = Math.ceil(frames / cols);
  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'clipcut-sheet-'));
  try {
    for (let i = 1; i <= frames; i++) {
      const ts = Math.max(start, Math.min(end - 0.05, start + ((i - 0.5) * dur) / frames));
      const fp = path.join(tmp, `f${i}.png`);
      const r = await runFf('ffmpeg', ['-v', 'error', '-y', '-ss', fmt(ts), '-i', video, '-frames:v', '1', '-vf', `scale=${width}:-2`, fp]);
      if (r.code !== 0 || !fs.existsSync(fp)) throw new UserError(`sheet frame extraction failed at ${fmt(ts)}s: ${r.stderr.trim().slice(0, 200)}`);
    }
    const rt = await runFf('ffmpeg', ['-v', 'error', '-y', '-start_number', '1', '-i', path.join(tmp, 'f%d.png'), '-vf', `tile=${cols}x${rows}`, '-frames:v', '1', outPng]);
    if (rt.code !== 0) throw new UserError(`contact sheet tiling failed: ${rt.stderr.trim().slice(0, 200)}`);
  } finally { fs.rmSync(tmp, { recursive: true, force: true }); }
}

/** Read a duration off a media file (format.duration). */
async function durationOf(file) {
  const r = await runFf('ffprobe', ['-v', 'error', '-show_entries', 'format=duration', '-of', 'json', file]);
  if (r.code !== 0) throw new UserError(`ffprobe failed on ${file}: ${r.stderr.trim().slice(0, 200)}`);
  const d = Number(JSON.parse(r.stdout.toString()).format?.duration);
  if (!Number.isFinite(d) || d <= 0) throw new UserError(`Could not read a duration from ${file}.`);
  return d;
}

/** Load segments.json: { segments, video, duration } — "segments" records video+duration so
 * later steps (sheets/read) can warn when handed a different video. */
function loadSegmentsDoc(p) {
  let j;
  try { j = readJson(p); } catch { throw new UserError(`segments file is not valid JSON: ${p}`); }
  const segs = Array.isArray(j) ? j : (j && Array.isArray(j.segments) ? j.segments : null);
  if (!segs || !segs.length) throw new UserError(`${p} has no segments — run "clipcut.mjs segments <probe.json>" first.`);
  for (const s of segs) {
    if (s == null || !Number.isFinite(Number(s.start)) || !Number.isFinite(Number(s.end)) || Number(s.end) <= Number(s.start)) {
      throw new UserError(`${p} has a segment without numeric start < end: ${JSON.stringify(s).slice(0, 120)}`);
    }
  }
  return {
    segments: segs.map((s, i) => ({ id: s.id || `seg_${String(i + 1).padStart(3, '0')}`, start: Number(s.start), end: Number(s.end) })),
    video: j && typeof j.video === 'string' ? j.video : null,
    duration: j && Number.isFinite(Number(j.duration)) ? Number(j.duration) : null,
  };
}

/** Warn when a derived-from-a-video JSON is used against a different video (path or >1s duration). */
function sameVideoPath(a, b) {
  // realpath both so symlinked dirs (/tmp vs /private/tmp on macOS) don't fire spurious warnings
  const r = (p) => { try { return fs.realpathSync(path.resolve(p)); } catch { return path.resolve(p); } };
  return r(a) === r(b);
}
function warnSourceMismatch(what, derivedVideo, derivedDuration, video, actualDuration) {
  if (derivedVideo && !sameVideoPath(derivedVideo, video)) {
    console.log(`warning: ${what} was built for ${derivedVideo} but got ${path.resolve(video)}`);
  }
  if (derivedDuration != null && Number.isFinite(actualDuration) && Math.abs(derivedDuration - actualDuration) > 1) {
    console.log(`warning: ${what} says the source is ${fmt(derivedDuration)}s but ${path.resolve(video)} is ${fmt(actualDuration)}s (mismatch > 1s)`);
  }
}

/** Sheet list from the sheets.json manifest ONLY — never a PNG glob: a crashed sheets run
 * leaves partial PNGs behind, and rating half a set would look like a complete answer. */
function listSheets(dir) {
  if (!fs.existsSync(dir) || !fs.statSync(dir).isDirectory()) throw new UserError(`Sheets dir not found: ${dir}. Run "clipcut.mjs sheets" first.`);
  const mp = path.join(dir, 'sheets.json');
  if (!fs.existsSync(mp)) throw new UserError(`No sheets.json manifest in ${dir} — re-run "clipcut.mjs sheets" into this dir (a partial sheet set is never used).`);
  let manifest;
  try { manifest = readJson(mp); } catch { throw new UserError(`sheets.json in ${dir} is not valid JSON — re-run "clipcut.mjs sheets" into a fresh dir.`); }
  const listed = manifest && Array.isArray(manifest.sheets) ? manifest.sheets : [];
  if (!listed.length) throw new UserError(`sheets.json in ${dir} lists no sheets — re-run "clipcut.mjs sheets".`);
  const files = listed.map((s) => ({ id: s.id, path: path.join(dir, s.file), file: s.file }));
  for (const f of files) if (!fs.existsSync(f.path)) throw new UserError(`Sheet listed but missing on disk: ${f.path}`);
  const framesPer = Number(manifest.frames_per_sheet) || 6;
  return { files, framesPer };
}

// ---------------------------------------------------------------- commands: doctor

async function cmdDoctor(o) {
  const problems = [];
  const nodeMajor = Number(process.versions.node.split('.')[0]);
  console.log(`node                  : ${process.version} ${nodeMajor >= 18 ? 'ok' : 'TOO OLD (need 18+)'}`);
  if (nodeMajor < 18) problems.push('Node older than 18');
  const c = cfg();
  console.log(`CLOUDFLARE_ACCOUNT_ID : ${c.accountId ? `set (from ${envSource('CLOUDFLARE_ACCOUNT_ID')})` : 'missing'}`);
  console.log(`CLOUDFLARE_API_TOKEN  : ${c.token ? `set (from ${envSource('CLOUDFLARE_API_TOKEN')})` : 'missing'}`);
  if (!c.accountId) problems.push('CLOUDFLARE_ACCOUNT_ID missing (needed for rate, read --engine clairic and doctor --ping)');
  if (!c.token) problems.push('CLOUDFLARE_API_TOKEN missing (needed for rate, read --engine clairic and doctor --ping)');
  console.log(`ai gateway            : ${c.gateway ? `configured (from ${envSource('CLEFCUT_GATEWAY_ID')})` : 'not configured (direct Workers AI)'}`);
  try {
    const t = await locate();
    if (t.version) console.log(`ffmpeg                : ${t.ffmpeg} (source: ${t.source}) — ${t.version}`);
    else { console.log(`ffmpeg                : FAILED to run (${t.ffmpeg})`); problems.push('no working ffmpeg (compositor packages and PATH all failed — run with CLEFCUT_FFMPEG set)'); }
  } catch (e) { console.log('ffmpeg                : NOT FOUND'); problems.push(`no ffmpeg: ${e.message}`); }
  const kind = await localOcrKind();
  console.log(`ocr tesseract.js      : ${kind === 'tesseract.js' ? 'yes (resolved from project node_modules; downloads English traineddata on first run)' : 'no'}`);
  console.log(`ocr system tesseract  : ${kind === 'system-tesseract' ? 'yes (on PATH)' : 'no'}`);
  if (o.ping) {
    if (!c.accountId || !c.token) { console.log('ping                  : skipped (credentials missing)'); problems.push('cannot ping without credentials'); }
    else {
      const t0 = Date.now();
      try {
        const r = await postAi('@cf/cloudflare/clef-flash', { model: 'clef-flash', state: 'Connectivity check.', questions: { ok: { type: 'noul', instructions: 'Is 2+2 equal to 4?' } } }, {});
        console.log(`ping                  : ok in ${Date.now() - t0}ms — p(yes)=${r && r.answers && r.answers.ok ? r.answers.ok.noul : '?'} tokens in=${r && r.usage ? r.usage.input_tokens : '?'} out=${r && r.usage ? r.usage.output_tokens : '?'}`);
      } catch (e) { console.log(`ping                  : FAILED — ${e.message}`); problems.push(`ping failed: ${e.message}`); }
    }
  }
  console.log(problems.length ? `\n${problems.length} problem(s)` : '\nall checks ok');
  return problems.length ? 1 : 0;
}

// ---------------------------------------------------------------- commands: probe / segments

async function cmdProbe(video, o) {
  if (!fs.existsSync(video)) throw new UserError(`Video not found: ${video}`);
  const threshold = numFlag(o, 'scene-threshold', SCENE_THRESHOLD, { min: 0, max: 1 });
  const info = await probeContainer(video);
  // (a) scene scores — metadata=print writes EVERY frame to a temp FILE (the file= option):
  // stderr is capped in runExe, so a stderr pass silently drops the head of long videos
  // (~66 B/frame; a 60-min video needs ~7 MB). Parsing the file keeps full coverage.
  const sceneFile = path.join(os.tmpdir(), `clipcut-scenes-${process.pid}-${Date.now()}.txt`);
  let scenes = [];
  try {
    const rs = await runFf('ffmpeg', ['-v', 'error', '-i', video, '-an', '-vf', `select='gte(scene,0)',metadata=print:file=${escapeFilterPath(sceneFile)}`, '-f', 'null', '-']);
    if (rs.code !== 0) throw new UserError(`scene scan failed on ${video}: ${rs.stderr.trim().slice(0, 300)}`);
    scenes = parseSceneMetadata(readTextOrNull(sceneFile) || '');
  } finally { fs.rmSync(sceneFile, { force: true }); }
  const sceneChanges = sceneMaxima(scenes, threshold);
  // (b) silence map (audio only).
  let silences = [];
  if (info.hasAudio) {
    const rsi = await runFf('ffmpeg', ['-i', video, '-vn', '-af', SILENCE_FILTER, '-f', 'null', '-']);
    silences = parseSilences(rsi.stderr)
      .map((s) => (s.end == null && info.duration > s.start ? { ...s, end: +info.duration.toFixed(3) } : s))
      .map((s) => ({ start: +Number(s.start).toFixed(3), end: s.end == null ? null : +Number(s.end).toFixed(3), ...(s.duration != null ? { duration: +Number(s.duration).toFixed(3) } : {}) }));
  }
  // (c) loudness — loudnorm JSON first, ebur128 summary as fallback (whichever parses cleanly).
  let loudness = null;
  if (info.hasAudio) {
    const rl = await runFf('ffmpeg', ['-i', video, '-af', 'loudnorm=print_format=json', '-f', 'null', '-']);
    loudness = parseLoudnormJson(rl.stderr);
    if (!loudness) {
      const re = await runFf('ffmpeg', ['-i', video, '-af', 'ebur128=peak=true', '-f', 'null', '-']);
      loudness = parseEbur128(re.stderr);
    }
  }
  // (d) keyframes — video packets with the K flag. This prints to STDOUT and runExe never
  // caps stdout (~40 B/packet; a 60-min 30fps video is ~4 MB), so coverage is complete.
  const rk = await runFf('ffprobe', ['-v', 'error', '-select_streams', 'v', '-show_packets', '-show_entries', 'packet=pts_time,flags', video]);
  const keyframes = parseKeyframes(rk.stdout.toString());
  const probe = {
    video: path.resolve(video),
    duration: +info.duration.toFixed(3), fps: +info.fps.toFixed(3),
    width: info.width, height: info.height,
    ...(info.rotation != null ? { rotation: info.rotation } : {}),
    vfr: info.vfr, has_audio: info.hasAudio,
    fingerprint: fingerprintFile(video),
    scene_threshold: threshold,
    scenes, scene_changes: sceneChanges,
    silences, loudness, keyframes,
    generated_at: new Date().toISOString(),
  };
  const outPath = o.out || 'probe.json';
  fs.writeFileSync(outPath, JSON.stringify(probe, null, 2));
  console.log(`${path.basename(video)}: ${info.width}x${info.height} @ ${fmt(info.fps)}fps, ${fmt(info.duration)}s${info.rotated ? ` (rotation ${fmt(info.rotation)}deg metadata: coded ${info.codedWidth}x${info.codedHeight}, displays ${info.width}x${info.height})` : ''}${info.vfr ? ' (VFR suspected)' : ''}${info.hasAudio ? '' : ' (no audio)'}`);
  console.log(`scenes: ${scenes.length} scored frame(s) -> ${sceneChanges.length} change point(s) at threshold ${threshold}${sceneChanges.length ? ` (first: ${sceneChanges.slice(0, 5).map(fmt).join(', ')}${sceneChanges.length > 5 ? ', ...' : ''})` : ''}`);
  console.log(`silence: ${silences.length} region(s)${silences.length ? ` (longest ${(Math.max(...silences.map((s) => (s.end ?? info.duration) - s.start))).toFixed(1)}s)` : ''}${info.hasAudio ? '' : ' — skipped, no audio'}`);
  console.log(`loudness: ${loudness ? `I=${loudness.I} LUFS, true peak=${loudness.TP == null ? '?' : loudness.TP} dBTP` : 'unavailable'}${info.hasAudio ? '' : ' — skipped, no audio'}`);
  console.log(`keyframes: ${keyframes.length}${keyframes.length ? ` (first: ${keyframes.slice(0, 5).map(fmt).join(', ')}${keyframes.length > 5 ? ', ...' : ''})` : ''}`);
  console.log(`fingerprint: size ${probe.fingerprint.size} bytes, sha256(head:tail) ${probe.fingerprint.sha256_head_tail.slice(0, 24)}... — carry it into clips.json so cut can refuse a swapped file (--strict)`);
  console.log(`wrote ${outPath}`);
  return 0;
}

async function cmdSegments(probePath, o) {
  if (!probePath) throw new UserError('usage: clipcut.mjs segments <probe.json> [--min 15] [--max 90] [--count 10] [--even-split N] [--out segments.json]');
  let probe;
  try { probe = readJson(probePath); } catch { throw new UserError(`probe file is not valid JSON: ${probePath}`); }
  if (!probe || !Number.isFinite(Number(probe.duration))) throw new UserError(`${probePath} has no "duration" — re-run "clipcut.mjs probe <video>".`);
  const min = numFlag(o, 'min', 15, { min: 0.1 });
  const max = numFlag(o, 'max', 90, { min: 0.1 });
  const count = numFlag(o, 'count', 10, { min: 1, max: 1000 });
  if (min >= max) throw new UserError(`--min (${min}) must be smaller than --max (${max}).`);
  const duration = Number(probe.duration);
  const evenSplit = o['even-split'] != null ? numFlag(o, 'even-split', 2, { min: 1, max: 1000 }) : null;
  let segments = [];
  let notes = null;
  if (evenSplit) {
    segments = evenSplitSegments(duration, evenSplit, {
      sceneChanges: Array.isArray(probe.scene_changes) ? probe.scene_changes : [],
      silences: Array.isArray(probe.silences) ? probe.silences : [],
    }).map((s, i) => ({ id: `seg_${String(i + 1).padStart(3, '0')}`, rank: i + 1, ...s }));
    notes = [`mechanical: --even-split ${evenSplit} produced equal divisions of the video, not content-aware picks`];
  } else {
    const built = buildSegments(probe, { min, max, count });
    segments = built.segments;
    notes = built.notes || null;
    if (!segments.length && duration > max) {
      console.error(`no candidate segments: the video is ${fmt(duration)}s but no boundary-delimited piece fits [${min}, ${max}]s. Lower --min, re-run "clipcut.mjs probe" with a lower --scene-threshold to expose more cut points, or pass --even-split N for N equal mechanical segments.`);
      return 1;
    }
  }
  const doc = {
    probe: path.resolve(probePath), video: probe.video || null, duration: +duration.toFixed(3),
    // inherited so every downstream artifact carries the source's identity
    ...(probe.fingerprint ? { fingerprint: probe.fingerprint } : {}),
    min, max, count, generated_at: new Date().toISOString(),
    segments, ...(notes ? { notes } : {}),
  };
  const outPath = o.out || 'segments.json';
  fs.writeFileSync(outPath, JSON.stringify(doc, null, 2));
  console.log(`${segments.length} candidate segment(s) in [${min}, ${max}]s from ${path.basename(probePath)}${evenSplit ? ' (--even-split: mechanical)' : ''}:`);
  for (const s of segments) console.log(`  ${s.id}: ${fmt(s.start)}s-${fmt(s.end)}s (${fmt(s.duration)}s)${s.mechanical ? ' mechanical' : ` score=${s.score} scenes=${s.signals.scenes} silence_cut=${s.signals.silence_cut}`}`);
  console.log(`wrote ${outPath}`);
  return 0;
}

// ---------------------------------------------------------------- commands: sheets

async function cmdSheets(video, o) {
  if (!fs.existsSync(video)) throw new UserError(`Video not found: ${video}`);
  if (!o.segments) throw new UserError('--segments segments.json is required (run "clipcut.mjs segments" first).');
  const doc = loadSegmentsDoc(o.segments);
  const segments = doc.segments;
  const info = await probeContainer(video);
  warnSourceMismatch('the segments file', doc.video, doc.duration, video, info.duration);
  const frames = numFlag(o, 'frames', 6, { min: 1, max: 12 });
  const out = o.out || 'sheets';
  prepareManagedDir(out, (e) => /^seg_[A-Za-z0-9._-]*\.png$/.test(e) || e === 'sheets.json');
  const sheets = [];
  for (const seg of segments) {
    const file = `${seg.id}.png`;
    await contactSheet(video, { start: seg.start, end: seg.end, frames, outPng: path.join(out, file) });
    sheets.push({ id: seg.id, file, start: seg.start, end: seg.end, duration: +(seg.end - seg.start).toFixed(3) });
    console.log(`${file}: ${fmt(seg.start)}s-${fmt(seg.end)}s, ${frames} frames, tile ${frames <= 4 ? 2 : 3}x${Math.ceil(frames / (frames <= 4 ? 2 : 3))}`);
  }
  fs.writeFileSync(path.join(out, 'sheets.json'), JSON.stringify({
    video: path.resolve(video), frames_per_sheet: frames, sheet_width: 480,
    created_at: new Date().toISOString(), sheets,
  }, null, 2));
  console.log(`wrote ${path.join(out, 'sheets.json')} (${sheets.length} sheet(s))`);
  return 0;
}

// ---------------------------------------------------------------- commands: rate (CLEF)

async function cmdRate(o) {
  const sheetsDir = o.sheets || o._[1];
  if (!sheetsDir) throw new UserError('--sheets sheets/ is required (run "clipcut.mjs sheets" first).');
  if (!o.questions) throw new UserError('--questions questions.json is required. See --help for the schema.');
  let spec;
  try { spec = readJson(o.questions); } catch { throw new UserError(`--questions file is not valid JSON: ${o.questions}`); }
  validateQuestions(spec);
  const pass = spec.pass || {};
  const margin = typeof spec.escalate_margin === 'number' ? spec.escalate_margin : 0.3;
  const severity = spec.severity || {};
  const escalateOnly = new Set(spec.escalate_only || []);
  const model = o.model || 'clef-flash';
  if (!['clef', 'clef-flash', 'clef-omni'].includes(model)) throw new UserError('--model must be clef, clef-flash or clef-omni.');
  const size = imageBatchSize(o, 1); // one sheet per request by default: per-segment truth
  requireCreds(); // credentials BEFORE anything is read, gated or sent
  const { files, framesPer } = listSheets(sheetsDir);
  const state = RATE_STATE_TEMPLATE.replace('{N}', String(framesPer));
  const dims = await imageDims(files[0].path);
  preflightGate(files, dims, { model, size, yes: yesFlag(o) });

  const modelFull = `@cf/cloudflare/${model}`;
  const makeBody = (images) => ({ model, state, questions: spec.questions, images });
  const usage = { input_tokens: 0, output_tokens: 0, requests: 0 };
  const requestRows = [];
  const parts = []; // {files, result, isolated, needIsolate, superseded}
  const outPath = o.out || 'ratings.json';
  const worstOf = (result) => {
    let worst = 'pass';
    for (const [qid, q] of Object.entries(spec.questions)) {
      const cls = classifyAnswer(q, (result.answers || {})[qid] || null, pass[qid], margin, escalateOnly.has(qid));
      if (cls === 'fail') { worst = 'fail'; break; }
      if (cls === 'escalate') worst = 'escalate';
    }
    return worst;
  };
  const assemble = (complete, error = null) => {
    const segments = [];
    for (const p of parts) {
      if (p.superseded) continue;
      const answers = [];
      let worst = 'pass';
      for (const [qid, q] of Object.entries(spec.questions)) {
        const raw = (p.result.answers || {})[qid] || null;
        const cls = classifyAnswer(q, raw, pass[qid], margin, escalateOnly.has(qid));
        if (cls === 'fail') worst = 'fail';
        else if (cls === 'escalate' && worst !== 'fail') worst = 'escalate';
        answers.push({ question: qid, type: q.type, raw, probability: defectProb(q, raw), classification: cls, severity: severity[qid] || null });
      }
      segments.push({ segment: p.files[0].id, sheets: p.files.map((f) => f.file), isolated: !!p.isolated, worst, answers });
    }
    return {
      model, gateway: o.gateway || cfg().gateway || null, generated_at: new Date().toISOString(), complete, state,
      requests: requestRows, segments, usage,
      cost_estimate_usd: +((usage.input_tokens * (PRICES[model] ?? 0)) / 1e6).toFixed(6),
      ...(error ? { error } : {}),
    };
  };
  const write = (complete, error = null) => fs.writeFileSync(outPath, JSON.stringify(assemble(complete, error), null, 2));
  const emit = (slice, result, isolated) => {
    const u = (result && result.usage) || {};
    usage.input_tokens += u.input_tokens || 0; usage.output_tokens += u.output_tokens || 0; usage.requests += 1;
    requestRows.push({ segments: slice.map((f) => f.id), isolated: !!isolated, usage: u });
    parts.push({ files: slice, result, isolated: !!isolated, needIsolate: worstOf(result) !== 'pass', superseded: false });
    write(false); // incremental: ratings.json rewritten after every request
  };
  try {
    for (const batch of buildBatches(files, { size })) {
      const start = parts.length;
      await requestBatch(modelFull, makeBody, batch, { gateway: o.gateway }, emit);
      const batchParts = parts.slice(start);
      // Auto-isolation: a multi-sheet batch with any fail/escalate is re-asked one image
      // per request; per-segment rows replace the batch rows (usage of both passes recorded).
      if (batch.length > 1 && batchParts.some((p) => p.needIsolate)) {
        for (const p of batchParts) p.superseded = true;
        for (const f of batch) await requestBatch(modelFull, makeBody, [f], { gateway: o.gateway, isolated: true }, emit);
      }
    }
  } catch (e) {
    write(false, redact(e.message)); // fatal mid-run: partial ratings.json stays on disk, then exit 2
    throw e;
  }
  write(true);
  const final = assemble(true);
  const tally = { fail: 0, escalate: 0, pass: 0 };
  for (const s of final.segments) tally[s.worst]++;
  console.log(`model: ${model} — ${usage.requests} request(s), ${final.segments.length} segment(s) rated`);
  console.log(`  fail=${tally.fail} escalate=${tally.escalate} pass=${tally.pass}`);
  const isolatedRows = final.segments.filter((s) => s.isolated).length;
  if (isolatedRows) console.log(`auto-isolation: ${requestRows.filter((r) => r.isolated).length} sheet(s) re-asked one image per request`);
  console.log(usageLine(model, usage));
  console.log(`ratings written to ${outPath}`);
  return tally.fail || tally.escalate ? 1 : 0;
}

// ---------------------------------------------------------------- commands: read (OCR / CLAIRIC)

async function cmdRead(input, o) {
  if (!input) throw new UserError('usage: clipcut.mjs read <video|sheetsDir> --segments segments.json [--engine local|clairic|auto]');
  if (!fs.existsSync(input)) throw new UserError(`Input not found: ${input}`);
  if (!o.segments) throw new UserError('--segments segments.json is required (run "clipcut.mjs segments" first).');
  const segDoc = loadSegmentsDoc(o.segments);
  const segments = segDoc.segments;
  const isDir = fs.statSync(input).isDirectory();
  // Engine chosen ONCE per run and reported.
  const want = o.engine || 'auto';
  let engine = want;
  let engineNote = '';
  if (want === 'local' || want === 'auto') {
    const kind = await localOcrKind();
    if (kind) { engine = kind; if (want === 'auto') engineNote = ` (auto → local: ${kind})`; }
    else if (want === 'local') throw new UserError('No local OCR available. Install one: npm i -D tesseract.js (downloads English traineddata on first run) or install system tesseract. Or use --engine clairic.');
    else { engine = 'clairic'; engineNote = ' (auto → clairic: no local OCR found)'; }
  } else if (want !== 'clairic') throw new UserError('--engine must be local, clairic or auto.');

  const outPath = o.out || 'text.json';
  let fields = DEFAULT_TEXT_FIELDS;
  if (o.fields) {
    try { fields = readJson(o.fields); } catch { throw new UserError(`--fields file is not valid JSON: ${o.fields}`); }
    if (!fields || typeof fields !== 'object' || !Object.keys(fields).length) throw new UserError('fields.json must be a non-empty object of field specs.');
    for (const [id, f] of Object.entries(fields)) if (!f || typeof f !== 'object' || !f.type) throw new UserError(`field "${id}": needs at least {"type": "text"|"number"|...}.`);
  }

  // One image per segment: the sheet (sheets dir input) or the midpoint frame (video input).
  let files;
  let tmpDir = null;
  if (isDir) {
    const listed = listSheets(input).files;
    const byId = new Map(listed.map((f) => [f.id, f]));
    files = segments.map((seg) => byId.get(seg.id)).filter(Boolean);
    const missing = segments.length - files.length;
    if (!files.length) throw new UserError(`No sheet in ${input} matches a segment id from ${o.segments}.`);
    if (missing) console.log(`note: ${missing} segment(s) have no matching sheet in ${input} — skipped`);
    if (engine === 'clairic') requireCreds(); // credentials BEFORE any network
  } else {
    if (engine === 'clairic') requireCreds(); // credentials BEFORE any frame extraction
    warnSourceMismatch('the segments file', segDoc.video, segDoc.duration, input, await durationOf(input));
    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'clipcut-read-'));
    files = [];
    for (const seg of segments) {
      const mid = seg.start + (seg.end - seg.start) / 2;
      const fp = path.join(tmpDir, `${seg.id}.png`);
      // Width capped at 1280 (no upscaling: min(1280,iw)) to bound tokens/bytes.
      const r = await runFf('ffmpeg', ['-v', 'error', '-y', '-ss', fmt(mid), '-i', input, '-frames:v', '1', '-vf', "scale='min(1280,iw)':-2", fp]);
      if (r.code !== 0 || !fs.existsSync(fp)) throw new UserError(`midpoint frame extraction failed for ${seg.id} at ${fmt(mid)}s: ${r.stderr.trim().slice(0, 200)}`);
      files.push({ id: seg.id, path: fp, file: `${seg.id}.png` });
    }
  }
  try {
    if (engine !== 'clairic') {
      const rows = await ocrImages(engine, files);
      fs.writeFileSync(outPath, JSON.stringify({ engine: `${engine}${engineNote}`.trim(), complete: true, segments: rows, usage: null }, null, 2));
      console.log(`engine: ${engine}${engineNote} (local, free)`);
      console.log(`wrote ${outPath} (${rows.length} segment record(s))`);
      return 0;
    }
    // clairic: 1 image per request (per-segment truth), paced, incremental writes. The
    // state tells the model WHAT it is looking at: a contact sheet (dir input) or a single
    // midpoint frame (video input).
    const state = isDir ? READ_STATE_SHEET : READ_STATE;
    const dims = await imageDims(files[0].path);
    preflightGate(files, dims, { model: 'clairic', size: 1, yes: yesFlag(o) });
    const usage = { input_tokens: 0, output_tokens: 0, requests: 0 };
    const requestRows = [];
    const rows = [];
    const write = (complete, error = null) => fs.writeFileSync(outPath, JSON.stringify({
      engine: `clairic${engineNote}`, gateway: o.gateway || cfg().gateway || null, generated_at: new Date().toISOString(), complete,
      requests: requestRows, segments: rows, usage, cost_estimate_usd: +((usage.input_tokens * PRICES.clairic) / 1e6).toFixed(6),
      ...(error ? { error } : {}),
    }, null, 2));
    try {
      for (const batch of buildBatches(files, { size: 1 })) {
        await requestBatch('@cf/cloudflare/clairic', (images) => ({ model: 'clairic', state, fields, images }), batch, { gateway: o.gateway }, (slice, result) => {
          const u = (result && result.usage) || {};
          usage.input_tokens += u.input_tokens || 0; usage.output_tokens += u.output_tokens || 0; usage.requests += 1;
          requestRows.push({ segments: slice.map((f) => f.id), usage: u });
          const first = Object.values(result.answers || {})[0] || {};
          rows.push({ segment: slice[0].id, file: slice[0].file, engine: 'clairic', fields: result.answers || {}, text: first.value ?? null, confidence: first.confidence ?? null, p_null: first.p_null ?? null });
        });
        write(false);
      }
    } catch (e) { write(false, redact(e.message)); throw e; }
    write(true);
    console.log(`engine: clairic${engineNote} (${usage.requests} request(s))`);
    console.log(usageLine('clairic', usage));
    if (Object.keys(fields).length > 1) console.log('note: with multiple fields, text/confidence reflect the FIRST field');
    console.log(`wrote ${outPath} (${rows.length} segment record(s))`);
    return 0;
  } finally {
    if (tmpDir) fs.rmSync(tmpDir, { recursive: true, force: true });
  }
}

// ---------------------------------------------------------------- commands: cut

async function cmdCut(video, o) {
  if (!fs.existsSync(video)) throw new UserError(`Video not found: ${video}`);
  if (!o.plan) throw new UserError('--plan clips.json is required. See "clipcut.mjs plan" for the schema.');
  let plan;
  try { plan = readJson(o.plan); } catch { throw new UserError(`--plan file is not valid JSON: ${o.plan}`); }
  const mode = o.mode || 'lossless';
  if (!['lossless', 'accurate'].includes(mode)) throw new UserError('--mode must be lossless or accurate.');
  const tolerance = numFlag(o, 'tolerance', 0.5, { min: 0.001 });
  const outdir = o.outdir || 'clips';
  // Probe + validate the source BEFORE touching the output dir: a corrupt source must
  // never empty --outdir (the clear below only runs once the source is known-good).
  const info = await probeContainer(video);
  const v = validatePlan(plan, info.duration);
  if (v.errors.length) throw new UserError(`clips.json invalid: ${v.errors.join('; ')}. See "clipcut.mjs plan" for the schema.`);
  for (const w of v.warnings) console.log(`warning: ${w}`);
  if (typeof plan.video === 'string' && !sameVideoPath(plan.video, video)) {
    console.log(`warning: clips.json was built for ${plan.video} but cutting ${path.resolve(video)}`);
  }
  if (Number.isFinite(Number(plan.duration)) && Math.abs(Number(plan.duration) - info.duration) > 1) {
    console.log(`warning: clips.json says the source is ${fmt(plan.duration)}s but it is ${fmt(info.duration)}s (mismatch > 1s)`);
  }
  // Input fingerprint: when the plan carries one (copied from probe.json), compare it
  // to the ACTUAL file. A re-rendered source at the same path with the same duration
  // still trips this — path/duration checks cannot. Mismatch is a loud warning;
  // --strict turns it into exit 2 BEFORE any cutting (and before the output dir is
  // touched).
  if (plan.fingerprint) {
    const actual = fingerprintFile(video);
    const match = fingerprintsMatch(plan.fingerprint, actual);
    if (match === false) {
      const msg = `fingerprint mismatch: the plan was built from a DIFFERENT file (same path/duration?) — plan fingerprint (size ${plan.fingerprint.size}, sha256 head:tail ${String(plan.fingerprint.sha256_head_tail).slice(0, 16)}...) vs actual (size ${actual.size}, sha256 head:tail ${actual.sha256_head_tail.slice(0, 16)}...) — re-run probe + segments against this file`;
      if (o.strict === true) throw new UserError(`${msg}. --strict refuses to cut; nothing was written`);
      console.log(`warning: ${msg}; pass --strict to refuse`);
    }
  }
  // Managed dir: cut-report.json + any tool-named clip/export output (<slug>.mp4 and the
  // <slug>_<platform>_<variant>.mp4 family) may stay from earlier runs — re-running cut
  // for one clip in the same dir works. Only the stale report is cleared upfront; clip
  // files are replaced by ATOMIC rename (verified temp first), so a failed cut leaves a
  // pre-existing clip untouched instead of a truncated file.
  prepareManagedDirKeep(outdir, (e) => e === 'cut-report.json' || /^[A-Za-z0-9][A-Za-z0-9._-]*\.mp4$/.test(e), ['cut-report.json']);
  if (mode === 'lossless' && info.vfr) console.log(`note: source looks VFR (r=${fmt(info.r_frame_rate)} vs avg=${fmt(info.avg_frame_rate)} fps) — copy cuts may drift; every clip will be re-encoded`);
  // Keyframe map (stdout pass in probe style — never truncated): used for copy-mode
  // start_error_ms AND for nearest_keyframes / lossless_alternative on every re-encode
  // path (accurate mode, VFR fallback, tolerance fallback), so it is fetched for all
  // modes (~40 B/packet; a 60-min 30fps video is ~4 MB — complete coverage).
  const rk = await runFf('ffprobe', ['-v', 'error', '-select_streams', 'v', '-show_packets', '-show_entries', 'packet=pts_time,flags', video]);
  const keyframes = parseKeyframes(rk.stdout.toString());

  const outPath = (slug) => path.join(outdir, `${slug}.mp4`);
  const measure = async (f) => durationOf(f);
  /** First packet pts of one stream (null when unreadable) — feeds av_start_skew_s. */
  const firstPacketPts = async (file, sel) => {
    const rp = await runFf('ffprobe', ['-v', 'error', '-select_streams', sel, '-read_intervals', '%+#1', '-show_entries', 'packet=pts_time', '-of', 'csv=p=0', file]);
    if (rp.code !== 0) return null;
    const first = rp.stdout.toString().split(/\r?\n/).map((l) => l.trim()).filter(Boolean)[0];
    const n = Number(first);
    return Number.isFinite(n) ? n : null;
  };
  const rows = [];
  for (const c of plan.clips) {
    const dur = +(c.end - c.start).toFixed(3);
    const target = outPath(c.slug);
    const fadeStart = Math.max(0, dur - FADE_S).toFixed(3);
    const encodeArgs = (out) => [
      '-v', 'error', '-y', '-ss', fmt(c.start), '-i', video, '-t', fmt(dur),
      '-c:v', 'libx264', '-crf', '18', '-preset', 'medium', '-pix_fmt', 'yuv420p',
      ...(info.hasAudio ? ['-c:a', 'aac', '-b:a', '192k', '-af', `afade=t=in:st=0:d=${FADE_S},afade=t=out:st=${fadeStart}:d=${FADE_S}`] : []),
      '-movflags', '+faststart', out,
    ];
    const copyArgs = (out) => ['-v', 'error', '-y', '-ss', fmt(c.start), '-i', video, '-t', fmt(dur), '-c', 'copy', '-avoid_negative_ts', 'make_zero', out];
    // Atomic write: encode/copy into a hidden temp sibling, verify (readable duration;
    // faststart on re-encode paths), then rename onto the final name.
    const writeClip = async (argsFor, what, { wantFaststart = false } = {}) => {
      await atomicMediaWrite(target, async (tmp) => {
        const r = await runFf('ffmpeg', argsFor(tmp));
        if (r.code !== 0) throw new UserError(`${what} failed: ${r.stderr.trim().slice(0, 300)}`);
      }, async (tmp) => {
        await durationOf(tmp); // throws when the output is unreadable
        if (wantFaststart && !hasFaststart(tmp)) throw new UserError(`${what}: verification failed — output has no faststart (moov not at the front); nothing written`);
      });
    };
    const bracket = bracketKeyframes(keyframes, c.start);
    const tolMs = Math.round(tolerance * 1000);
    let used = '';
    let command = '';
    let nearestKeyframes = null;
    let losslessAlt = null;
    if (mode === 'accurate' || info.vfr) {
      await writeClip(encodeArgs, `accurate cut of ${c.slug}`, { wantFaststart: true }); used = 're-encode'; command = encodeArgs(target).join(' ');
      nearestKeyframes = bracket;
      losslessAlt = {
        command: `ffmpeg ${copyArgs(target).join(' ')}`,
        reason: mode === 'accurate' ? '--mode accurate was requested (always re-encodes)' : 'source looks VFR — copy cuts can start on a frozen or wrong frame',
      };
    } else {
      await writeClip(copyArgs, `lossless cut of ${c.slug}`); used = 'copy'; command = copyArgs(target).join(' ');
      const first = classifyDuration(await measure(target), dur, tolerance);
      if (!first.within) {
        const snapMs = bracket.before == null ? null : Math.round((c.start - bracket.before) * 1000);
        await writeClip(encodeArgs, `accurate re-cut of ${c.slug}`, { wantFaststart: true }); used = 're-encode (tolerance fallback)'; command = encodeArgs(target).join(' ');
        nearestKeyframes = bracket;
        losslessAlt = {
          command: `ffmpeg ${copyArgs(target).join(' ')}`,
          reason: snapMs != null && snapMs > tolMs
            ? `keyframe snap ${snapMs}ms exceeds tolerance ${tolMs}ms`
            : `copy duration error ${first.error_ms}ms exceeded tolerance ${tolMs}ms${snapMs != null ? ` (start keyframe snap ${snapMs}ms)` : ''}`,
        };
      }
    }
    const actual = await measure(target);
    const { error_ms, within } = classifyDuration(actual, dur, tolerance);
    // Copy mode snaps -ss to the keyframe at-or-before the requested start: record how far
    // earlier than requested the clip actually begins (null when the keyframe map is empty).
    let startErr = null;
    let avSkew = null;
    let avSkewWarn = false;
    if (used === 'copy') {
      const kf = keyframeAtOrBefore(keyframes, c.start);
      startErr = kf == null ? null : Math.round((c.start - kf) * 1000);
      if (info.hasAudio) {
        // Copy-mode joins can start audio and video at slightly different pts. Warning
        // field only — it does NOT change the exit semantics of this command.
        const vPts = await firstPacketPts(target, 'v');
        const aPts = await firstPacketPts(target, 'a');
        if (vPts != null && aPts != null) {
          avSkew = +Math.abs(vPts - aPts).toFixed(3);
          const limit = Math.max(2 / (info.fps || 30), 0.1);
          if (avSkew > limit) {
            avSkewWarn = true;
            console.log(`warning: ${c.slug}: audio starts ${fmt(avSkew)}s away from video (over the ${fmt(limit)}s limit) — copy-mode joins can click or drift; re-cut with --mode accurate if that matters`);
          }
        }
      }
    }
    rows.push({
      slug: c.slug, file: target, mode: used, requested_s: dur, actual_s: +actual.toFixed(3),
      duration_error_ms: error_ms, within_tolerance: within,
      ...(used === 'copy' ? { start_error_ms: startErr } : {}),
      ...(used === 'copy' && avSkew != null ? { av_start_skew_s: avSkew, ...(avSkewWarn ? { av_start_skew_warning: true } : {}) } : {}),
      ...(used !== 'copy' ? { nearest_keyframes: nearestKeyframes, lossless_alternative: losslessAlt } : {}),
      command: `ffmpeg ${command}`,
    });
    console.log(`${c.slug}: mode=${used.startsWith('copy') ? 'copy' : 're-encode'} requested=${fmt(dur)}s actual=${fmt(actual)}s err=${error_ms}ms${used === 'copy' && startErr != null ? ` start_err=${startErr}ms` : ''}${avSkew != null ? ` av_skew=${fmt(avSkew)}s` : ''} ${within ? 'ok' : 'OVER TOLERANCE'}`);
  }
  const report = {
    video: path.resolve(video), plan: path.resolve(o.plan), mode, tolerance_s: tolerance,
    source_vfr: info.vfr, generated_at: new Date().toISOString(), clips: rows,
  };
  fs.writeFileSync(path.join(outdir, 'cut-report.json'), JSON.stringify(report, null, 2));
  console.log(`wrote ${path.join(outdir, 'cut-report.json')}`);
  const failing = rows.filter((r) => !r.within_tolerance);
  if (failing.length) {
    console.log(`attention needed: duration error > ${tolerance}s for: ${failing.map((r) => r.slug).join(', ')}`);
    return 1;
  }
  return 0;
}

// ---------------------------------------------------------------- commands: export

const PLATFORM_NOTES = {
  youtube: 'youtube: long-form accepts most aspect ratios; H.264 High + AAC + faststart (moov at the front) recommended; ~8 Mbps for 1080p SDR at 24-30fps.',
  shorts: 'youtube shorts: vertical up to 3 minutes (verified cap), max 1080p; 9:16 1080x1920 recommended; keep text out of the top ~10% / bottom ~30% (community-measured).',
  tiktok: 'tiktok: 9:16 1080x1920 recommended (community-measured), H.264+AAC MP4; standard uploads allow up to ~10 min (community-reported); keep captions/CTAs clear of the bottom rail (~484px) and right icon rail (~140px) (community-measured).',
  reels: 'instagram reels: 9:16 recommended (1.91:1 minimum), 30+ fps, >=720p; 3-minute limit is community-reported (unverified); ads must keep the bottom 40% free of text/logos.',
  x: 'x: 16:9 / 1:1 / 9:16 accepted, 1080p max; free tier caps uploads at 140s (community-reported; Premium allows up to 4h); no auto-captions — burn them in.',
  creator: 'creator (generic profile): 9:16 1080x1920, H.264+AAC, faststart, even dimensions; aim for 60-90s per clip; keep critical content out of top ~15% / bottom ~30% / right ~10%.',
};

async function measureLoudnorm(file) {
  const r = await runFf('ffmpeg', ['-i', file, '-af', `loudnorm=I=${LOUDNORM_TARGET.I}:TP=${LOUDNORM_TARGET.TP}:LRA=${LOUDNORM_TARGET.LRA}:print_format=json`, '-f', 'null', '-']);
  const m = parseLoudnormJson(r.stderr);
  if (!m || !Number.isFinite(m.I) || !Number.isFinite(m.threshold)) throw new UserError(`loudnorm measurement failed on ${file} (silent or unmeasurable audio).`);
  return m;
}

async function cmdExport(clip, o) {
  if (!clip || !fs.existsSync(clip)) throw new UserError(`Clip not found: ${clip}`);
  const platform = o.platform;
  if (!platform) throw new UserError(`--platform is required: ${PLATFORMS.join('|')}.`);
  if (!PLATFORMS.includes(platform)) throw new UserError(`--platform must be one of ${PLATFORMS.join('|')}. Got: ${platform}`);
  const variant = o.variant || 'original';
  if (!VARIANTS.includes(variant)) throw new UserError(`--variant must be one of ${VARIANTS.join('|')}. Got: ${variant}`);
  // Crop anchors: window-position fractions for 9x16-crop ONLY (0 = left/top edge,
  // 1 = right/bottom edge, 0.5 = centered default). Anywhere else they would do
  // nothing — reject instead of silently ignoring.
  const anchorGiven = o['crop-x'] != null || o['crop-y'] != null;
  if (anchorGiven && variant !== '9x16-crop') throw new UserError('crop anchors apply to 9x16-crop only (on other variants the crop window has no free position)');
  const cropX = cropAnchor(o['crop-x'], 'crop-x');
  const cropY = cropAnchor(o['crop-y'], 'crop-y');
  const outdir = o.out || 'exports';
  const slug = sanitizeSlug(path.basename(clip));
  const target = path.join(outdir, exportName(slug, platform, variant));
  // Managed dir: only this tool's export naming family is allowed (plus this tool's own
  // stale atomic-write temps, which are cleared). The target itself is NOT removed
  // upfront — the write is atomic (verified temp, then rename), so a failed export
  // leaves a pre-existing export untouched instead of nothing.
  if (fs.existsSync(outdir)) {
    if (!fs.statSync(outdir).isDirectory()) throw new UserError(`--out path exists and is not a directory: ${outdir}`);
    for (const e of fs.readdirSync(outdir)) {
      if (!EXPORT_NAME_RE.test(e) && !TEMP_OUTPUT_RE.test(e)) throw new UserError(`output dir has unrelated files; choose a fresh --out (found "${e}" in ${outdir})`);
    }
    for (const e of fs.readdirSync(outdir)) if (TEMP_OUTPUT_RE.test(e)) fs.rmSync(path.join(outdir, e), { force: true });
  }
  fs.mkdirSync(outdir, { recursive: true });

  const info = await probeContainer(clip);
  let af = null;
  let loudnormNote = '';
  if (o.loudnorm === true) {
    if (!info.hasAudio) { loudnormNote = ' (--loudnorm skipped: clip has no audio)'; console.log('note: --loudnorm skipped — clip has no audio'); }
    else {
      const m = await measureLoudnorm(clip); // pass 1: measure
      af = `loudnorm=I=${LOUDNORM_TARGET.I}:TP=${LOUDNORM_TARGET.TP}:LRA=${LOUDNORM_TARGET.LRA}:measured_I=${m.I}:measured_TP=${m.TP ?? LOUDNORM_TARGET.TP}:measured_LRA=${m.LRA ?? LOUDNORM_TARGET.LRA}:measured_thresh=${m.threshold}:linear=true`;
      loudnormNote = ` (loudnorm two-pass: measured I=${m.I} LUFS → target ${LOUDNORM_TARGET.I})`;
    }
  }
  const audioArgs = af
    ? ['-c:a', 'aac', '-b:a', '192k', '-af', af]
    : (info.hasAudio ? ['-c:a', 'copy'] : []);
  const videoEncode = ['-c:v', 'libx264', '-crf', '18', '-preset', 'medium', '-pix_fmt', 'yuv420p'];
  const faststart = ['-movflags', '+faststart'];

  let args;
  let label;
  let blurFgH = null;
  if (variant === '9x16-blur') {
    const fc = '[0:v]scale=1080:1920:force_original_aspect_ratio=increase,crop=1080:1920,boxblur=20:2[bg];[0:v]scale=1080:-2[fg];[bg][fg]overlay=(W-w)/2:(H-h)/2,setsar=1[v]';
    args = ['-v', 'error', '-y', '-i', clip, '-filter_complex', fc, '-map', '[v]', '-map', '0:a?', ...videoEncode, ...audioArgs, ...faststart];
    label = '9x16 blur-pad re-encode';
    if (Number.isFinite(info.width) && info.width > 0) blurFgH = Math.round((info.height * 1080) / info.width);
  } else if (variant === '9x16-crop') {
    // Bounded crop: min(iw,ih*9/16) x min(ih,iw*16/9) never exceeds the frame in either
    // dimension, so ANY aspect (portrait/taller-than-9:16, landscape, square) fills 1080x1920.
    // --crop-x/--crop-y anchor the window inside the leftover region (0.5 = the
    // byte-identical historical center crop; see cropAnchorFilter).
    args = ['-v', 'error', '-y', '-i', clip, '-vf', cropAnchorFilter(cropX, cropY), ...videoEncode, ...audioArgs, ...faststart];
    label = cropX === 0.5 && cropY === 0.5 ? '9x16 center-crop re-encode' : `9x16 anchored-crop re-encode (crop-x ${cropX}, crop-y ${cropY})`;
  } else if (!evenDims(info.width, info.height)) {
    args = ['-v', 'error', '-y', '-i', clip, '-vf', 'scale=trunc(iw/2)*2:trunc(ih/2)*2', ...videoEncode, ...audioArgs, ...faststart];
    label = `re-encode to even dimensions (${info.width}x${info.height} is odd)`;
  } else if ((info.codec && info.codec !== PLATFORM_CODEC.video) || (info.pixFmt && info.pixFmt !== PLATFORM_CODEC.pixFmt)) {
    // Original-variant baseline from the shared table: even dims are not enough — a
    // non-H.264 or non-yuv420p stream (hevc, vp9, yuv444...) is stream-copied into an
    // export platforms reject, so it re-encodes to the PLATFORM_CODEC baseline.
    args = ['-v', 'error', '-y', '-i', clip, ...videoEncode, ...audioArgs, ...faststart];
    label = `re-encode to the ${PLATFORM_CODEC.video}/${PLATFORM_CODEC.pixFmt} baseline (source is ${info.codec || '?'}/${info.pixFmt || '?'})`;
  } else if (af) {
    args = ['-v', 'error', '-y', '-i', clip, '-c:v', 'copy', ...audioArgs, ...faststart];
    label = 'audio re-encode (loudnorm), video stream-copied';
  } else {
    args = ['-v', 'error', '-y', '-i', clip, '-c', 'copy', ...faststart];
    label = `stream copy remux (already compliant${hasFaststart(clip) ? ', faststart normalized' : ''})`;
  }
  // Atomic write: encode into a hidden temp sibling, verify (readable container + a
  // faststart box walk — every export path adds +faststart), then rename onto the target.
  await atomicMediaWrite(target, async (tmp) => {
    const r = await runFf('ffmpeg', [...args, tmp]);
    if (r.code !== 0) throw new UserError(`export failed (${label}): ${r.stderr.trim().slice(0, 300)}`);
  }, async (tmp) => {
    await probeContainer(tmp);
    if (!hasFaststart(tmp)) throw new UserError(`export verification failed (${label}): output has no faststart (moov not at the front); nothing written`);
  });
  const outInfo = await probeContainer(target);
  const warnings = platformWarnings(platform, outInfo.duration, { width: outInfo.width, height: outInfo.height }, variant);
  console.log(`${PLATFORM_NOTES[platform]}`);
  console.log(`wrote ${target} — ${outInfo.width}x${outInfo.height}, ${fmt(outInfo.duration)}s, faststart=${hasFaststart(target)}${loudnormNote} [${label}]`);
  if (blurFgH != null && blurFgH > 1920) {
    // Taller-than-9:16 portrait: the foreground fitted to 1080px wide is taller than the
    // 1920px canvas, so the overlay centers and the top/bottom fall off the canvas.
    console.log(`warning: 9x16-blur on ${info.width}x${info.height} (taller than 9:16): the foreground fitted to 1080px wide is ~${blurFgH}px tall and exceeds the 1920px canvas — vertical content is cropped`);
  }
  for (const w of warnings) console.log(`warning: ${w}`);
  if (warnings.length) { console.log('attention needed: platform spec warnings above'); return 1; }
  return 0;
}

// ---------------------------------------------------------------- commands: tighten

// AUDIO ROUTE (empirical): kajisho5/ffmpeg-skill reports FFmpeg 8/8.1 `aselect` passing
// every frame through (nothing dropped). Verified locally on ffmpeg 9.0.2 (Homebrew):
// aselect DOES drop correctly here — 3 s wav with one 1 s span removed -> 1.978 s;
// 12 s mp4 keeping 8 s -> audio 8.006 s / video 8.067 s (both tracks dropped the same
// 4 s). CHOSEN ROUTE: direct `select` + `aselect` (+ pts resets) in ONE re-encode,
// guarded by the atomic post-write duration verification — on a build where aselect
// misbehaves (everything passes through) the output duration check fails, the temp is
// deleted and nothing is written, instead of a silently wrong file.
async function cmdTighten(clip, o) {
  if (!clip || !fs.existsSync(clip)) throw new UserError(`Clip not found: ${clip}`);
  const threshold = numFlag(o, 'threshold', TIGHTEN_DEFAULTS.thresholdDb, { min: -100, max: -1 });
  const minSilence = numFlag(o, 'min-silence', TIGHTEN_DEFAULTS.minSilenceS, { min: 0.05, max: 60 });
  const margin = numFlag(o, 'margin', TIGHTEN_DEFAULTS.marginS, { min: 0, max: 2 });
  const minKeep = numFlag(o, 'min-keep', TIGHTEN_DEFAULTS.minKeepS, { min: 0, max: 30 });
  const maxCuts = numFlag(o, 'max-cuts', TIGHTEN_DEFAULTS.maxCuts, { min: 1, max: 5000 });
  const info = await probeContainer(clip); // throws on a missing video stream
  if (!info.hasAudio) throw new UserError(`${clip} has no audio stream — tighten removes silence detected on AUDIO; nothing to tighten.`);
  if (info.vfr) console.log(`warning: VFR source (r=${fmt(info.r_frame_rate)} vs avg=${fmt(info.avg_frame_rate)} fps) — tighten re-times the video to CFR (select + setpts), re-encode forced`);
  const duration = info.duration;
  const rsi = await runFf('ffmpeg', ['-i', clip, '-vn', '-af', `silencedetect=noise=${threshold}dB:d=${minSilence}`, '-f', 'null', '-']);
  const silences = parseSilences(rsi.stderr)
    .map((s) => (s.end == null && duration > s.start ? { ...s, end: +duration.toFixed(3) } : s))
    .map((s) => ({ start: +Number(s.start).toFixed(3), end: s.end == null ? null : +Number(s.end).toFixed(3) }));
  const { keep, cuts, removedS } = buildKeepSpans(duration, silences, { margin, minKeep });

  // Nothing to tighten: measure the track mean level and SUGGEST a threshold (mean + 6 dB,
  // capped at -5 dB) instead of returning an empty nothing.
  if (!keep.length || removedS < 0.05) {
    const rv = await runFf('ffmpeg', ['-i', clip, '-vn', '-af', 'volumedetect', '-f', 'null', '-']);
    const vol = parseVolumedetect(rv.stderr);
    const meanDb = vol ? vol.mean : null;
    if (meanDb != null && meanDb <= SILENT_MAX_DB) {
      console.log(`nothing to tighten at threshold ${threshold} dBFS / min-silence ${minSilence}s — and the audio measures as digital silence (mean ${meanDb} dBFS): there is no speech to keep.`);
    } else {
      const suggestion = suggestThreshold(meanDb);
      console.log(`nothing to tighten at threshold ${threshold} dBFS / min-silence ${minSilence}s: no removable silence found${meanDb != null ? ` — the track mean level is ${meanDb} dBFS; try --threshold ${suggestion}` : ''}`);
    }
    return 0;
  }
  if (cuts > maxCuts) {
    throw new UserError(`${cuts} silence cuts exceeds --max-cuts ${maxCuts} (the select filter graph would be oversized). Raise --min-silence (fewer, longer silences), --margin, or --max-cuts.`);
  }

  const stem = sanitizeSlug(path.basename(clip));
  const target = path.join(path.dirname(path.resolve(clip)), `${stem}_tight.mp4`);
  const expr = keep.map(([a, b]) => `between(t,${fmt(a)},${fmt(b)})`).join('+');
  // 30 ms audio de-click at every JOIN (end of kept piece i meets start of piece i+1),
  // placed at the CUMULATIVE output timestamps (post-asetpts the audio is contiguous).
  // NOT afade: afade=t=in with st>0 silences everything BEFORE st, so a fade-in at a
  // join would zero every earlier kept piece. A per-frame conditional volume filter
  // ramps down into each join and back up out of it, leaving all other samples at 1.
  const fadeJoin = fadeJoinExpr;
  const fadeList = [];
  let cum = 0;
  for (let i = 0; i < keep.length - 1; i++) {
    cum += keep[i][1] - keep[i][0];
    fadeList.push(`volume=volume='${fadeJoin(cum)}':eval=frame`);
  }
  const vf = `select='${expr}',setpts=N/FRAME_RATE/TB`;
  const af = [`aselect='${expr}',asetpts=N/SR/TB`, ...fadeList].join(',');
  const expectedS = +keep.reduce((a, k) => a + (k[1] - k[0]), 0).toFixed(3);
  // Single re-encode, written atomically: the temp is verified before it replaces
  // anything at <stem>_tight.mp4 — duration must match the keep-span total AND the
  // output audio must not be silent (duration alone let a broken filter chain ship
  // a digitally-silent file; volumedetect is the backstop).
  const srcVol = await measureMaxVolume(clip);
  await atomicMediaWrite(target, async (tmp) => {
    const r = await runFf('ffmpeg', ['-v', 'error', '-y', '-i', clip, '-vf', vf, '-af', af,
      '-c:v', 'libx264', '-crf', '18', '-preset', 'medium', '-pix_fmt', 'yuv420p',
      '-c:a', 'aac', '-b:a', '192k', '-movflags', '+faststart', tmp]);
    if (r.code !== 0) throw new UserError(`tighten encode failed: ${r.stderr.trim().slice(0, 300)}`);
  }, async (tmp) => {
    const d = await durationOf(tmp);
    const { within } = classifyDuration(d, expectedS, 0.5);
    if (!within) throw new UserError(`tighten verification failed: output is ${fmt(d)}s but the keep spans total ${fmt(expectedS)}s — this ffmpeg build may not drop audio frames in aselect; no file written.`);
    if (srcVol != null && srcVol > SILENT_MAX_DB) {
      const outVol = await measureMaxVolume(tmp);
      if (outVol != null && outVol <= SILENT_MAX_DB) {
        throw new UserError(`tighten verification failed: the source audio peaks at ${srcVol} dBFS but the output is digitally silent (<= ${SILENT_MAX_DB} dBFS) — a filter chain destroyed the audio; no file written.`);
      }
    }
  });
  const after = await durationOf(target);
  console.log(`tighten: ${path.basename(clip)} -> ${path.basename(target)} (threshold ${threshold} dBFS, min-silence ${minSilence}s, margin ${margin}s, min-keep ${minKeep}s)`);
  console.log(`report: before_s=${fmt(duration)} after_s=${fmt(after)} removed_s=${fmt(Math.max(0, duration - after))} cuts=${cuts}`);
  return 0;
}

// ---------------------------------------------------------------- commands: check

async function cmdCheck(file, o) {
  if (!file || !fs.existsSync(file)) throw new UserError(`File not found: ${file}`);
  const platform = o.platform || null;
  if (platform && !PLATFORMS.includes(platform)) throw new UserError(`--platform must be one of ${PLATFORMS.join('|')} or omitted. Got: ${platform}`);
  const facts = await probeCheckFacts(file);
  const rows = buildCheckRows(facts, { platform });
  const summary = { pass: 0, warn: 0, fail: 0 };
  for (const r of rows) summary[r.status === 'FAIL' ? 'fail' : r.status === 'WARN' ? 'warn' : 'pass']++;
  const outPath = o.out || 'check-report.json';
  fs.writeFileSync(outPath, JSON.stringify({
    file: path.resolve(file), platform, generated_at: new Date().toISOString(),
    rows, summary,
  }, null, 2));
  console.log(`check: ${path.basename(file)}${platform ? ` against ${platform} (duration cap ${PLATFORM_SPECS[platform].duration.cap == null ? 'none' : `${PLATFORM_SPECS[platform].duration.cap}s`} — ${PLATFORM_SPECS[platform].duration.mark})` : ' (no --platform: judgement rows are WARN-only, format rows still enforce)'}`);
  for (const r of rows) {
    console.log(`  ${r.status.padEnd(4)} ${r.check} [${r.kind}]${r.note ? ` — ${r.note}` : ''}`);
    if (r.reason) console.log(`       reason: ${r.reason}`);
    if (r.fix) console.log(`       fix: ${r.fix}`);
  }
  console.log(`summary: ${summary.pass} PASS, ${summary.warn} WARN, ${summary.fail} FAIL`);
  console.log(`wrote ${outPath}`);
  return summary.fail ? 1 : 0;
}

// ---------------------------------------------------------------- commands: preview / plan

const PREVIEW_NAME_RE = /^[A-Za-z0-9][A-Za-z0-9._-]*_(?:preview\.png|3s\.mp4|end3s\.mp4)$/;

async function cmdPreview(clip, o) {
  if (!clip || !fs.existsSync(clip)) throw new UserError(`Clip not found: ${clip}`);
  const slug = sanitizeSlug(path.basename(clip));
  const outdir = o.out || 'preview';
  const sheetName = `${slug}_preview.png`;
  const first3Name = `${slug}_3s.mp4`;
  const end3Name = `${slug}_end3s.mp4`;
  // Managed dir: ANY slug's preview outputs may coexist; only THIS slug's files + the
  // report are replaced, so previewing several clips into one dir just works.
  prepareManagedDirKeep(outdir, (e) => e === 'preview.json' || PREVIEW_NAME_RE.test(e), [sheetName, first3Name, end3Name, 'preview.json']);
  const dur = await durationOf(clip);
  await contactSheet(clip, { start: 0, end: dur, frames: 6, outPng: path.join(outdir, sheetName) });
  const sample = async (name, seek, len) => {
    const r = await runFf('ffmpeg', ['-v', 'error', '-y', '-ss', fmt(seek), '-i', clip, '-t', fmt(len), '-vf', 'scale=320:-2', '-an', '-c:v', 'libx264', '-crf', '20', '-preset', 'fast', '-pix_fmt', 'yuv420p', '-movflags', '+faststart', path.join(outdir, name)]);
    if (r.code !== 0) throw new UserError(`preview sample ${name} failed: ${r.stderr.trim().slice(0, 300)}`);
  };
  const headLen = Math.min(3, dur);
  const tailLen = Math.min(3, dur);
  await sample(first3Name, 0, headLen);
  await sample(end3Name, Math.max(0, dur - tailLen), tailLen);

  // Boundary check: for each clip edge, a scene-score scan of the SOURCE over [t-1.5, t+1.5]
  // records the max scene score in the window and whether a scene change lands within 0.5s
  // of the boundary (from the window scan itself; --probe cross-checks its scene_changes).
  const boundaries = [];
  let boundariesNote = 'boundary check skipped — pass --source <video> --start S --end E (optional --probe probe.json) to score the clip edges';
  if (o.source) {
    if (!fs.existsSync(o.source)) throw new UserError(`--source not found: ${o.source}`);
    const start = numFlag(o, 'start', null, { min: 0 });
    const end = numFlag(o, 'end', null, { min: 0 });
    if (start == null || end == null) throw new UserError('--source needs --start S and --end E (the clip\'s times in the source) for the boundary check');
    if (end <= start) throw new UserError('--end must be greater than --start');
    let probeData = null;
    if (o.probe) {
      if (!fs.existsSync(o.probe)) throw new UserError(`--probe file not found: ${o.probe}`);
      try { probeData = readJson(o.probe); } catch { throw new UserError(`--probe file is not valid JSON: ${o.probe}`); }
    }
    const srcDur = await durationOf(o.source);
    const scan = async (type, t) => {
      // Start 0.1s early: input-seeking drops the first frame pair, which would
      // understate scene_score_max exactly at the boundary being checked.
      const t0 = Math.max(0, t - 1.6);
      const windowS = +Math.max(0, Math.min(srcDur, t + 1.5) - t0).toFixed(3);
      const tmp = path.join(os.tmpdir(), `clipcut-bound-${process.pid}-${Date.now()}-${type}.txt`);
      let windowScenes = [];
      try {
        const r = await runFf('ffmpeg', ['-v', 'error', '-ss', fmt(t0), '-i', o.source, '-t', fmt(windowS), '-an', '-vf', `select='gte(scene,0)',metadata=print:file=${escapeFilterPath(tmp)}`, '-f', 'null', '-']);
        if (r.code !== 0) throw new UserError(`boundary scan failed at ${fmt(t)}s: ${r.stderr.trim().slice(0, 300)}`);
        // -ss before -i rebases timestamps to the window start — map back to source time.
        windowScenes = parseSceneMetadata(readTextOrNull(tmp) || '')
          .map((s) => (Number.isFinite(s.t) ? { t: +(t0 + s.t).toFixed(3), score: s.score } : s));
      } finally { fs.rmSync(tmp, { force: true }); }
      const res = boundaryScan(windowScenes, t);
      const row = { type, t: +Number(t).toFixed(3), window_s: windowS, scene_score_max: res.scene_score_max, scene_change_near: res.scene_change_near };
      if (probeData && Array.isArray(probeData.scene_changes)) row.probe_scene_change_near = probeData.scene_changes.some((pt) => Math.abs(Number(pt) - t) <= 0.5);
      return row;
    };
    boundaries.push(await scan('start', start), await scan('end', end));
    boundariesNote = '';
  }
  const doc = {
    clip: slug,
    file: path.resolve(clip),
    samples: { sheet: path.join(outdir, sheetName), first3s: path.join(outdir, first3Name), last3s: path.join(outdir, end3Name) },
    boundaries,
    ...(boundariesNote ? { boundaries_note: boundariesNote } : {}),
    generated_at: new Date().toISOString(),
  };
  fs.writeFileSync(path.join(outdir, 'preview.json'), JSON.stringify(doc, null, 2));
  console.log(`wrote ${path.join(outdir, sheetName)} (6-frame contact sheet) + ${first3Name} (first ${fmt(headLen)}s) + ${end3Name} (last ${fmt(tailLen)}s) — samples muted, 320px wide`);
  for (const b of boundaries) {
    console.log(`${b.type} @ ${fmt(b.t)}s: max scene score ${b.scene_score_max == null ? 'n/a' : b.scene_score_max.toFixed(3)} over a ${fmt(b.window_s)}s window, scene change within 0.5s: ${b.scene_change_near}${b.probe_scene_change_near != null ? ` (probe agrees: ${b.probe_scene_change_near})` : ''}`);
  }
  if (!boundaries.length) console.log(boundariesNote);
  console.log(`wrote ${path.join(outdir, 'preview.json')}`);
  return 0;
}

function cmdPlan(o) {
  console.log(`clips.json schema (for "cut"):

{
  "video": "/abs/path/talk.mp4",       // optional: recorded source — cut warns on a mismatch
  "duration": 754.2,                   // optional: recorded source duration (seconds)
  "clips": [
    {
      "slug": "hook",                  // required: filename-safe id [A-Za-z0-9._-], unique
      "start": 12.5,                   // required: seconds, >= 0
      "end": 58.2,                     // required: seconds, > start (5-600s recommended)
      "variants": ["9x16-crop"],       // optional: original | 9x16-crop | 9x16-blur
      "platforms": ["shorts", "tiktok"]// optional: open list — known: ${PLATFORMS.join(' | ')}; unknown map to the creator profile
    }
  ]
}

Minimal example: {"clips":[{"slug":"teaser","start":0,"end":30}]}`);
  if (!o.file) return 0;
  let plan;
  try { plan = readJson(o.file); } catch { console.error(`error: --file is not valid JSON: ${o.file}`); return 2; }
  const v = validatePlan(plan);
  for (const e of v.errors) console.error(`invalid: ${e}`);
  for (const w of v.warnings) console.log(`warning: ${w}`);
  if (v.errors.length) { console.error(`clips.json is INVALID (${v.errors.length} error(s))`); return 2; }
  const { durations, total } = planDurations(plan.clips);
  plan.clips.forEach((c, i) => console.log(`  ${c.slug}: ${fmt(c.start)}s-${fmt(c.end)}s (${fmt(durations[i])}s)`));
  console.log(`total: ${fmt(total)}s across ${plan.clips.length} clip(s)`);
  if (v.warnings.length) { console.log(`clips.json is valid with ${v.warnings.length} warning(s)`); return 1; }
  console.log(`clips.json is valid (${plan.clips.length} clip(s))`);
  return 0;
}

// ---------------------------------------------------------------- commands: verify

/**
 * Generic verify step-runner (exported — selftested). Each step's fn returns
 * undefined (PASS), { skip: reason }, { note } / { skip, note }, or throws (FAIL).
 * After a FAIL the remaining steps SKIP with a reason naming the failed step —
 * every verify step depends on the same file, so cascading failures only add noise.
 * Returns { rows, failed }.
 */
export async function runVerifySteps(steps, log = () => {}) {
  const rows = [];
  let aborted = null;
  for (const s of steps || []) {
    let row;
    if (aborted) {
      row = { name: s.name, status: 'SKIP', reason: aborted };
    } else {
      try {
        const r = await s.fn();
        if (r && r.skip) row = { name: s.name, status: 'SKIP', reason: r.skip, ...(r.note ? { note: r.note } : {}) };
        else row = { name: s.name, status: 'PASS', ...(r && r.note ? { note: r.note } : {}) };
      } catch (e) {
        row = { name: s.name, status: 'FAIL', reason: (e && e.message) || String(e) };
        aborted = `earlier step failed: ${s.name}`;
      }
    }
    rows.push(row);
    log(row);
  }
  return { rows, failed: rows.some((r) => r.status === 'FAIL') };
}

/**
 * verify <video> [--net] — real-footage self-test: runs the REAL pipeline commands
 * (probe -> segments -> sheets -> cut -> tighten -> export 9x16-crop -> check ->
 * preview) against the user's own file in a temp dir under os.tmpdir() (always
 * cleaned). Network steps (one clef-flash ping + one clairic image) run only when
 * credentials exist AND --net was passed; otherwise they SKIP with a reason.
 * Per-step PASS/FAIL/SKIP-with-reason, one summary line, exit 1 on any FAIL.
 * Run once per machine and after ffmpeg upgrades.
 */
async function cmdVerify(video, o) {
  if (!video || !fs.existsSync(video)) throw new UserError(`Video not found: ${video}`);
  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'clipcut-verify-'));
  const paths = { probe: null, segments: null, firstSeg: null, sheet: null, clip: null, export: null };
  const steps = [];
  const step = (name, fn) => steps.push({ name, fn });

  step('probe', async () => {
    paths.probe = path.join(tmp, 'probe.json');
    const rc = await cmdProbe(video, { out: paths.probe });
    if (rc !== 0) throw new Error(`probe exited ${rc}`);
    const p = readJson(paths.probe);
    if (!(Number(p.duration) > 0)) throw new Error('probe.json carries no duration');
    if (!p.fingerprint || !p.fingerprint.sha256_head_tail) throw new Error('probe.json carries no fingerprint');
    return { note: `${p.width}x${p.height} @ ${fmt(p.fps)}fps, ${fmt(p.duration)}s, fingerprint size ${p.fingerprint.size}` };
  });

  step('segments', async () => {
    if (!paths.probe) return { skip: 'no probe to build segments from' };
    paths.segments = path.join(tmp, 'segments.json');
    const rc = await cmdSegments(paths.probe, { out: paths.segments });
    const doc = readJson(paths.segments);
    const segs = Array.isArray(doc.segments) ? doc.segments : [];
    if (!segs.length) {
      const dur = Number(readJson(paths.probe).duration) || 0;
      if (dur < 15) return { skip: `video is ${fmt(dur)}s — shorter than the 15s default --min, no candidate expected` };
      throw new Error(`no candidate segments (segments exited ${rc})`);
    }
    paths.firstSeg = segs[0];
    return { note: `${segs.length} candidate(s); using ${segs[0].id} ${fmt(segs[0].start)}s-${fmt(segs[0].end)}s` };
  });

  step('sheets', async () => {
    if (!paths.firstSeg) return { skip: 'no candidate segment to sheet' };
    const sheetsDir = path.join(tmp, 'sheets');
    const trimPath = path.join(tmp, 'segments-first.json');
    const doc = readJson(paths.segments);
    fs.writeFileSync(trimPath, JSON.stringify({ ...doc, segments: [paths.firstSeg] }, null, 2));
    await cmdSheets(video, { segments: trimPath, out: sheetsDir });
    const { files } = listSheets(sheetsDir);
    paths.sheet = files[0].path;
    if (!fs.existsSync(paths.sheet)) throw new Error('no sheet written');
    return { note: `${files.length} sheet(s): ${path.basename(paths.sheet)}` };
  });

  step('cut', async () => {
    if (!paths.firstSeg) return { skip: 'no candidate segment to slice' };
    const seg = paths.firstSeg;
    const sliceEnd = Math.min(seg.end, seg.start + 8);
    if (sliceEnd - seg.start < 1) return { skip: 'segment too short to slice' };
    const planPath = path.join(tmp, 'verify-plan.json');
    fs.writeFileSync(planPath, JSON.stringify({ video: path.resolve(video), clips: [{ slug: 'verify-slice', start: seg.start, end: +sliceEnd.toFixed(3) }] }));
    const clipsDir = path.join(tmp, 'clips');
    const rc = await cmdCut(video, { plan: planPath, outdir: clipsDir, tolerance: 0.5 });
    paths.clip = path.join(clipsDir, 'verify-slice.mp4');
    const report = readJson(path.join(clipsDir, 'cut-report.json'));
    const row = report.clips && report.clips[0];
    if (rc !== 0 || !row) throw new Error(`cut exited ${rc}${row ? ` (duration_error_ms=${row.duration_error_ms})` : ''}`);
    return { note: `mode=${row.mode}, duration_error_ms=${row.duration_error_ms}${row.within_tolerance ? '' : ' (OVER TOLERANCE — cut reported it)'}` };
  });

  step('tighten', async () => {
    if (!paths.clip) return { skip: 'no cut slice to tighten' };
    const info = await probeContainer(paths.clip);
    if (!info.hasAudio) return { skip: 'slice has no audio stream' };
    const rsi = await runFf('ffmpeg', ['-i', paths.clip, '-vn', '-af', `silencedetect=noise=${TIGHTEN_DEFAULTS.thresholdDb}dB:d=${TIGHTEN_DEFAULTS.minSilenceS}`, '-f', 'null', '-']);
    if (!parseSilences(rsi.stderr).length) return { skip: 'no silence detected in the slice (nothing to tighten)' };
    const rc = await cmdTighten(paths.clip, {});
    if (rc !== 0) throw new Error(`tighten exited ${rc}`);
    return { note: 'silence removal ran on the slice' };
  });

  step('export', async () => {
    if (!paths.clip) return { skip: 'no cut slice to export' };
    const outdir = path.join(tmp, 'exports');
    await cmdExport(paths.clip, { platform: 'shorts', variant: '9x16-crop', out: outdir, 'crop-x': '0.5' });
    paths.export = path.join(outdir, exportName('verify-slice', 'shorts', '9x16-crop'));
    if (!fs.existsSync(paths.export)) throw new Error('export wrote no file');
    const info = await probeContainer(paths.export);
    if (info.width !== 1080 || info.height !== 1920) throw new Error(`export dims ${info.width}x${info.height}, expected 1080x1920`);
    return { note: '1080x1920 (9x16-crop, default crop-x 0.5)' };
  });

  step('check', async () => {
    if (!paths.export) return { skip: 'no export to check' };
    const rc = await cmdCheck(paths.export, { platform: 'shorts', out: path.join(tmp, 'check-report.json') });
    const rep = readJson(path.join(tmp, 'check-report.json'));
    const s = rep.summary || { pass: 0, warn: 0, fail: 0 };
    if (rc !== 0) throw new Error(`check exited ${rc} — ${s.fail} FAIL row(s) (see the rows above)`);
    return { note: `${s.pass} PASS, ${s.warn} WARN, ${s.fail} FAIL (WARNs are fine)` };
  });

  step('preview', async () => {
    if (!paths.clip) return { skip: 'no cut slice to preview' };
    const outdir = path.join(tmp, 'preview');
    await cmdPreview(paths.clip, { out: outdir });
    for (const n of ['verify-slice_preview.png', 'verify-slice_3s.mp4', 'verify-slice_end3s.mp4']) {
      if (!fs.existsSync(path.join(outdir, n))) throw new Error(`preview output missing: ${n}`);
    }
    return { note: 'sheet + first3s + end3s samples written' };
  });

  step('rate+read (network)', async () => {
    if (o.net !== true) return { skip: 'network steps skipped — pass --net to include one clef-flash ping + one clairic image (tiny billed call, estimate)' };
    const c = cfg();
    if (!c.accountId || !c.token) return { skip: 'no credentials (CLOUDFLARE_ACCOUNT_ID / CLOUDFLARE_API_TOKEN)' };
    if (!paths.sheet) return { skip: 'no sheet to send' };
    const dims = await imageDims(paths.sheet);
    preflightGate([{ path: paths.sheet }], dims, { model: 'clairic', size: 1, yes: yesFlag(o) });
    await postAi('@cf/cloudflare/clef-flash', { model: 'clef-flash', state: 'Connectivity check.', questions: { ok: { type: 'noul', instructions: 'Is 2+2 equal to 4?' } } }, {});
    await requestBatch('@cf/cloudflare/clairic', (images) => ({ model: 'clairic', state: READ_STATE_SHEET, fields: DEFAULT_TEXT_FIELDS, images }), [{ id: 'seg_001', path: paths.sheet, file: path.basename(paths.sheet) }], {}, () => {});
    return { note: 'clef-flash ping ok + one clairic image read (cost gate respected)' };
  });

  try {
    console.log(`verify: ${path.resolve(video)} (temp dir ${tmp}, always cleaned)`);
    const { rows, failed } = await runVerifySteps(steps, (row) => {
      console.log(`  ${row.status.padEnd(4)} ${row.name}${row.reason ? ` — ${row.reason}` : ''}${row.note ? ` — ${row.note}` : ''}`);
    });
    const tally = { PASS: 0, SKIP: 0, FAIL: 0 };
    for (const r of rows) tally[r.status]++;
    console.log(`summary: ${tally.PASS} PASS, ${tally.SKIP} SKIP, ${tally.FAIL} FAIL${failed ? ' — a FAIL means this machine/pipeline is not trustworthy on this file; fix it before real runs' : ' — pipeline healthy on this file'}`);
    return failed ? 1 : 0;
  } finally {
    fs.rmSync(tmp, { recursive: true, force: true });
  }
}

// ---------------------------------------------------------------- selftest

async function cmdSelftest() {
  const fails = [];
  const eq = (name, got, want) => {
    const ok = JSON.stringify(got) === JSON.stringify(want);
    if (!ok) fails.push(`${name}: got ${JSON.stringify(got)} want ${JSON.stringify(want)}`);
    console.log(`${ok ? 'ok  ' : 'FAIL'} ${name}`);
  };
  const tmp = path.join(os.tmpdir(), `clipcut-selftest-${Date.now()}.env`);
  fs.writeFileSync(tmp, '# comment\nFOO=bar\nQUOTED="hello world"\nSQ=\'single\'\nexport EXPORTED=yes\n; semi\nNUM=42\nHASH=a # trailing\n');
  const parsed = parseEnvText(fs.readFileSync(tmp, 'utf8'));
  fs.unlinkSync(tmp);
  eq('env parser basic', parsed.FOO, 'bar');
  eq('env parser quotes', parsed.QUOTED, 'hello world');
  eq('env parser single quotes', parsed.SQ, 'single');
  eq('env parser export', parsed.EXPORTED, 'yes');
  eq('env parser number stays string', parsed.NUM, '42');
  eq('env parser inline comment', parsed.HASH, 'a');
  // .env precedence: home first, project overrides, process env wins over both.
  const layered = mergeEnvLayered({ PROC: 'yes' }, [
    { text: 'ONLY_HOME=home\nSHARED=home', label: 'home.env' },
    { text: 'SHARED=proj', label: 'proj.env' },
  ]);
  eq('env precedence project wins over home', layered.env.SHARED, 'proj');
  eq('env precedence home still applies', layered.env.ONLY_HOME, 'home');
  eq('env precedence process env wins', layered.env.PROC, 'yes');
  eq('env precedence source label', layered.sources.SHARED, 'proj.env');
  eq('chunk 17 by 4', chunkAll(Array.from({ length: 17 }, (_, i) => i), 4).map((c) => c.length), [4, 4, 4, 4, 1]);
  eq('chunk 0', chunkAll([], 4), []);
  eq('classify 0.9 vs 0.5 fail', classify(0.9, 0.5, 0.3, false), 'fail');
  eq('classify 0.4 in margin escalate', classify(0.4, 0.5, 0.3, false), 'escalate');
  eq('classify 0.1 pass', classify(0.1, 0.5, 0.3, false), 'pass');
  eq('classify null escalate', classify(null, 0.5, 0.3, false), 'escalate');
  eq('classify escalate_only', classify(0.99, 0.5, 0.3, true), 'escalate');
  eq('classify no threshold pass', classify(0.99, null, 0.3, false), 'pass');
  const realToken = process.env.CLOUDFLARE_API_TOKEN;
  process.env.CLOUDFLARE_API_TOKEN = 'tok_selftest_secret123';
  ENV_CACHE = null;
  eq('redact token', redact('Authorization failed for tok_selftest_secret123').includes('tok_selftest_secret123'), false);
  process.env.CLOUDFLARE_API_TOKEN = realToken;
  ENV_CACHE = null;
  eq('defectProb noul', defectProb({ type: 'noul' }, { noul: 0.7 }), 0.7);
  eq('defectProb score', defectProb({ type: 'score', criteria: ['a', 'b', 'c', 'd'] }, { score: 3 }), 1);
  eq('defectProb choice', defectProb({ type: 'choice', defect_options: ['bad'] }, { choice: 'bad', probabilities: { bad: 0.8 } }), 0.8);
  eq('defectProb missing', defectProb({ type: 'noul' }, null), null);
  // choice confidence floor: escalate below 0.5, NEVER against the pass threshold.
  eq('choice confidence floor escalates', classifyAnswer({ type: 'choice', defect_options: ['bad'] }, { choice: 'ok', probabilities: { ok: 0.95, bad: 0.05 }, confidence: 0.3 }, 0.5, 0.3, false), 'escalate');
  eq('choice confidence never uses pass threshold', classifyAnswer({ type: 'choice', defect_options: ['bad'] }, { choice: 'ok', probabilities: { ok: 0.9, bad: 0.1 }, confidence: 0.85 }, 0.9, 0.3, false), 'pass');
  // batch builder: <= size files AND <= 6 MiB cumulative raw bytes per batch.
  const MiB = 1024 * 1024;
  eq('batch builder byte cap splits', buildBatches([{ path: 'a', b: 4 * MiB }, { path: 'b', b: 3 * MiB }, { path: 'c', b: 100 }], { size: 4, sizeOf: (f) => f.b }).map((x) => x.length), [1, 2]);
  eq('batch builder respects max count', buildBatches([{ path: 'a', b: 1 }, { path: 'b', b: 1 }, { path: 'c', b: 1 }, { path: 'd', b: 1 }, { path: 'e', b: 1 }], { size: 2, sizeOf: (f) => f.b }).map((x) => x.length), [2, 2, 1]);
  eq('batch builder single oversized file alone', buildBatches([{ path: 'a', b: 7 * MiB }, { path: 'b', b: 1 }], { size: 4, sizeOf: (f) => f.b }).map((x) => x.length), [1, 1]);
  // validateQuestions: every id needs numeric pass in (0,1] or escalate_only.
  const vqMsg = (spec) => { try { validateQuestions(spec); return ''; } catch (e) { return e.message; } };
  eq('validateQuestions rejects missing pass', /missing for: bad_id/.test(vqMsg({ questions: { ok_id: { type: 'noul', instructions: 'x' }, bad_id: { type: 'noul', instructions: 'x' } }, pass: { ok_id: 0.5 } })), true);
  eq('validateQuestions rejects pass out of range', vqMsg({ questions: { a: { type: 'noul', instructions: 'x' } }, pass: { a: 1.5 } }) !== '', true);
  eq('validateQuestions accepts escalate_only', vqMsg({ questions: { a: { type: 'noul', instructions: 'x' } }, escalate_only: ['a'] }), '');
  // validateQuestions: API limits enforced locally (<=64 questions, score 2-10 levels, choice 2-255 options).
  const manyQ = { questions: {}, escalate_only: [] };
  for (let i = 0; i < 65; i++) { manyQ.questions[`q${i}`] = { type: 'noul', instructions: 'x' }; manyQ.escalate_only.push(`q${i}`); }
  eq('validateQuestions rejects >64 questions', /at most 64/.test(vqMsg(manyQ)), true);
  eq('validateQuestions rejects score >10 levels', /10 levels/.test(vqMsg({ questions: { a: { type: 'score', instructions: 'x', criteria: Array.from({ length: 11 }, (_, i) => `lvl${i}`) } }, escalate_only: ['a'] })), true);
  eq('validateQuestions rejects 1-option choice', /2-255 options/.test(vqMsg({ questions: { a: { type: 'choice', instructions: 'x', criteria: { only: 'x' } } }, escalate_only: ['a'] })), true);
  eq('validateQuestions accepts 255-option choice', vqMsg({ questions: { a: { type: 'choice', instructions: 'x', criteria: Object.fromEntries(Array.from({ length: 255 }, (_, i) => [`o${i}`, 'x'])) } }, escalate_only: ['a'] }), '');
  // arg parser: value flags demand a value; clean exit-2 error shape.
  const argMsg = (argv) => { try { parseArgs(argv); return ''; } catch (e) { return e.message; } };
  eq('arg parser missing value errors', /--questions requires a value/.test(argMsg(['rate', '--questions'])), true);
  eq('arg parser flags out value too', /--out requires a value/.test(argMsg(['probe', 'v.mp4', '--out', '--yes'])), true);
  eq('arg parser collects values', parseArgs(['probe', 'v.mp4', '--out', 'x.json']).out, 'x.json');
  eq('arg parser bare boolean flag', parseArgs(['cut', 'v.mp4', '--plan', 'p.json', '--yes']).yes, true);
  // URL builder: the FULL model id appears exactly once.
  eq('url builder single model id', runUrl('acc123', '@cf/cloudflare/clef-flash'), 'https://api.cloudflare.com/client/v4/accounts/acc123/ai/run/@cf/cloudflare/clef-flash');
  eq('token estimate caps at 1024', estTokensPerFrame(3840, 2160), 1024);
  eq('token estimate fallback', estTokensPerFrame(null, null), 600);
  eq('token estimate 960px frame is 513', estTokensPerFrame(960, 540), 513);
  // probe parsers.
  const sceneStderr = [
    'frame:28   pts:1120    pts_time:1.12',
    'lavfi.scene_score=0.000000',
    'frame:29   pts:1160    pts_time:1.16',
    'lavfi.scene_score=0.040000',
    'frame:30   pts:1200    pts_time:1.2',
    'lavfi.scene_score=0.834512',
  ].join('\n');
  eq('scene parser pairs pts_time with score', parseSceneMetadata(sceneStderr), [{ t: 1.12, score: 0 }, { t: 1.16, score: 0.04 }, { t: 1.2, score: 0.834512 }]);
  eq('scene parser ignores other metadata', parseSceneMetadata('frame:1 pts:40 pts_time:0.04\nlavfi.other=1\n'), []);
  eq('scene maxima keeps local peaks', sceneMaxima(parseSceneMetadata(sceneStderr), 0.03), [1.2]);
  eq('scene maxima threshold filters', sceneMaxima(parseSceneMetadata(sceneStderr), 0.9), []);
  const manyScenes = [0, 0.1, 0.9, 0.2, 0.85, 0.1, 0.7, 0.05].map((score, t) => ({ t, score }));
  eq('scene maxima multiple peaks sorted', sceneMaxima(manyScenes, 0.4), [2, 4, 6]);
  eq('scene maxima top-N cap', sceneMaxima(manyScenes, 0.4, 2), [2, 4]);
  const silenceStderr = [
    '[silencedetect @ 0x7fa] silence_start: 19.92',
    '[silencedetect @ 0x7fa] silence_end: 40.06 | silence_duration: 20.14',
    '[silencedetect @ 0x7fa] silence_start: 55.5',
  ].join('\n');
  eq('silence parser pairs start/end + duration', parseSilences(silenceStderr), [{ start: 19.92, end: 40.06, duration: 20.14 }, { start: 55.5, end: null }]);
  eq('silence parser empty', parseSilences('no markers here'), []);
  const loudnormStderr = '[Parsed_loudnorm_0 @ 0x7f8] \n{\n\t"input_i" : "-23.42",\n\t"input_tp" : "-8.61",\n\t"input_lra" : "0.10",\n\t"input_thresh" : "-33.92"\n}\n';
  eq('loudnorm json parser', parseLoudnormJson(loudnormStderr), { I: -23.42, TP: -8.61, LRA: 0.1, threshold: -33.92 });
  eq('loudnorm parser rejects garbage', parseLoudnormJson('nothing here'), null);
  const eburStderr = '[Parsed_ebur128_0 @ 0x7f8] Summary:\n\n  Integrated loudness:\n    I:         -23.4 LUFS\n    Threshold: -33.2 LUFS\n\n  True peak:\n    Peak:      -8.6 dBFS\n';
  eq('ebur128 parser extracts I and peak', parseEbur128(eburStderr), { I: -23.4, TP: -8.6, LRA: null, threshold: null });
  eq('ebur128 parser rejects garbage', parseEbur128('no summary'), null);
  const packetsStderr = '[PACKET]\npts_time=0.000000\nflags=K__\n[/PACKET]\n[PACKET]\npts_time=1.666667\nflags=__\n[/PACKET]\n[PACKET]\npts_time=N/A\nflags=K__\n[/PACKET]\n[PACKET]\npts_time=3.333333\nflags=K__\n[/PACKET]\n';
  eq('keyframe parser picks K flags (ceil to next ms)', parseKeyframes(packetsStderr), [0, 3.334]);
  eq('keyframe parser empty', parseKeyframes(''), []);
  // segments builder.
  const synth = { duration: 100, scene_changes: [20, 40, 60], silences: [{ start: 30, end: 32 }, { start: 50, end: 52 }], scenes: [{ t: 20, score: 0.9 }, { t: 40, score: 0.8 }], loudness: { I: -14, TP: -1.5 } };
  const built = buildSegments(synth, { min: 15, max: 30, count: 10 });
  const boundSet = [0, 20, 32, 40, 52, 60, 100];
  eq('segments all within [min,max]', built.segments.every((s) => s.duration >= 15 - 0.05 && s.duration <= 30 + 0.05), true);
  eq('segments boundaries respected', built.segments.every((s) => boundSet.includes(s.start) && boundSet.includes(s.end)), true);
  eq('segments count cap', buildSegments(synth, { min: 15, max: 30, count: 2 }).segments.length, 2);
  eq('segments ids assigned', buildSegments(synth, { min: 15, max: 30, count: 2 }).segments.map((s) => s.id), ['seg_001', 'seg_002']);
  const whole = buildSegments({ duration: 50, scene_changes: [], silences: [], scenes: [] }, { min: 15, max: 90, count: 10 });
  eq('segments whole video when shorter than max', whole.segments, [{ id: 'seg_001', rank: 1, start: 0, end: 50, duration: 50, score: 0, signals: { scenes: 0, silence_cut: false } }]);
  const silCut = built.segments.find((s) => s.start === 32);
  eq('segments silence_cut at silence end', silCut && silCut.signals.silence_cut, true);
  eq('segments no duration', buildSegments({}, { min: 15, max: 90 }).segments, []);
  // duration-error classifier.
  eq('duration error within tolerance', classifyDuration(15.02, 15, 0.5), { error_ms: 20, within: true });
  eq('duration error over tolerance', classifyDuration(16.2, 15, 0.5), { error_ms: 1200, within: false });
  eq('duration error missing values', classifyDuration(NaN, 15, 0.5), { error_ms: null, within: false });
  // plan validator.
  const badPlan = validatePlan({ clips: [{ slug: 'a b', start: 10, end: 5 }] });
  eq('plan rejects bad slug and start>=end', badPlan.errors.length >= 2, true);
  eq('plan rejects non-array', validatePlan({ clips: 'x' }).errors.length > 0, true);
  eq('plan accepts good plan', validatePlan({ clips: [{ slug: 'ok_clip', start: 0, end: 30 }] }), { errors: [], warnings: [] });
  eq('plan warns outside 5-600s', validatePlan({ clips: [{ slug: 'ok', start: 0, end: 601 }] }).warnings.length, 1);
  eq('plan rejects duplicate slugs', validatePlan({ clips: [{ slug: 'a', start: 0, end: 10 }, { slug: 'a', start: 20, end: 30 }] }).errors.length, 1);
  eq('plan warns when end beyond source duration', validatePlan({ clips: [{ slug: 'ok', start: 0, end: 30 }] }, 20).warnings.length, 1);
  const unkPlat = validatePlan({ clips: [{ slug: 'ok', start: 0, end: 30, platforms: ['nope'] }] });
  eq('plan accepts unknown platform with warning', [unkPlat.errors.length, unkPlat.warnings.length], [0, 1]);
  eq('plan unknown platform maps to creator profile', /mapping unknown platform 'nope' to the generic creator profile/.test(unkPlat.warnings[0]), true);
  // plan per-clip durations + total.
  eq('plan durations and total', planDurations([{ slug: 'a', start: 0, end: 10 }, { slug: 'b', start: 20, end: 30.5 }, { slug: 'bad', start: 5, end: 5 }]), { durations: [10, 10.5, null], total: 20.5 });
  // even-split: N equal mechanical divisions.
  const es = evenSplitSegments(100, 4);
  eq('even split count', es.length, 4);
  eq('even split math', es.map((s) => [s.start, s.end, s.duration]), [[0, 25, 25], [25, 50, 25], [50, 75, 25], [75, 100, 25]]);
  eq('even split flagged mechanical', es.every((s) => s.mechanical === true), true);
  const esSig = evenSplitSegments(100, 2, { sceneChanges: [60], silences: [{ start: 49.5, end: 50.2 }] });
  eq('even split signals computed', [esSig[0].signals.scenes, esSig[1].signals.scenes, esSig[1].signals.silence_cut], [0, 1, true]);
  // bounded 9:16 crop math: the window never exceeds the frame, any aspect fills 1080x1920.
  eq('crop target portrait 720x1600', cropTarget(720, 1600), { width: 720, height: 1280 });
  eq('crop target landscape 1920x1080', cropTarget(1920, 1080), { width: 607.5, height: 1080 });
  eq('crop target square 1080x1080', cropTarget(1080, 1080), { width: 607.5, height: 1080 });
  eq('crop target invalid dims', cropTarget(0, 100), { width: null, height: null });
  // boundary scorer: max window score + scene-change proximity.
  eq('boundary scan near edge', boundaryScan([{ t: 9.5, score: 0.1 }, { t: 9.8, score: 0.9 }], 10), { scene_score_max: 0.9, scene_change_near: true });
  eq('boundary scan not near edge', boundaryScan([{ t: 8.8, score: 0.95 }], 10), { scene_score_max: 0.95, scene_change_near: false });
  eq('boundary scan low scores not changes', boundaryScan([{ t: 9.9, score: 0.1 }], 10), { scene_score_max: 0.1, scene_change_near: false });
  eq('boundary scan empty window', boundaryScan([], 10), { scene_score_max: null, scene_change_near: false });
  // keyframe snap for copy-mode start_error_ms.
  eq('keyframe at or before picks latest', keyframeAtOrBefore([0, 2, 4, 6], 3.1), 2);
  eq('keyframe at or before exact', keyframeAtOrBefore([0, 2, 4], 2), 2);
  eq('keyframe at or before none', keyframeAtOrBefore([5, 6], 3), null);
  // platform warn rules.
  eq('platform x over 140s warns', platformWarnings('x', 150, {}, 'original').length >= 1, true);
  eq('platform x at 140s silent', platformWarnings('x', 140, {}, 'original').length, 0);
  eq('platform shorts over 180s warns', platformWarnings('shorts', 181, { width: 1080, height: 1920 }, 'original').length, 1);
  eq('platform youtube has no duration warn', platformWarnings('youtube', 200, { width: 1920, height: 1080 }, 'original').length, 0);
  eq('platform shorts warns when not 9:16', platformWarnings('shorts', 60, { width: 640, height: 360 }, 'original').length, 1);
  eq('platform shorts silent when 9:16', platformWarnings('shorts', 60, { width: 1080, height: 1920 }, '9x16-crop').length, 0);
  // per-platform duration wording (verified caps as fact, community limits hedged).
  eq('platform shorts warn text', platformWarnings('shorts', 181, { width: 1080, height: 1920 }, 'original')[0], 'duration 181s exceeds the 3-minute YouTube Shorts cap (verified)');
  eq('platform tiktok silent at 181s', platformWarnings('tiktok', 181, { width: 1080, height: 1920 }, 'original').length, 0);
  eq('platform tiktok warns from 570s', platformWarnings('tiktok', 570, { width: 1080, height: 1920 }, 'original')[0], 'duration 570s may exceed community-reported TikTok upload limits (unverified; standard uploads allow up to ~10 min)');
  eq('platform reels warn text', platformWarnings('reels', 181, { width: 1080, height: 1920 }, 'original')[0], 'duration 181s may exceed the community-reported 3-minute Reels limit (unverified)');
  eq('platform creator warn text', platformWarnings('creator', 91, { width: 1080, height: 1920 }, 'original')[0], 'duration 91s exceeds the 60–90s generic creator-platform guidance');
  eq('platform x warn text', platformWarnings('x', 141, {}, 'original')[0], 'duration 141s may exceed the community-reported 140s X free-tier limit (unverified; Premium allows up to 4h)');
  eq('platform tiktok at 569s silent', platformWarnings('tiktok', 569, { width: 1080, height: 1920 }, 'original').length, 0);
  // export naming.
  eq('export name format', exportName('my-clip', 'shorts', '9x16-crop'), 'my-clip_shorts_9x16-crop.mp4');
  eq('export name sanitizes slug', exportName('My Clip!.mp4', 'x', 'original'), 'My-Clip-_x_original.mp4');
  eq('sanitize slug fallback', sanitizeSlug('!!!'), 'clip');
  // platform specs: one table entry per platform id, judgement rows come from it.
  eq('platform specs cover every id', PLATFORMS.every((p) => PLATFORM_SPECS[p] && PLATFORM_SPECS[p].duration && PLATFORM_SPECS[p].aspects), true);
  eq('platform specs marks', PLATFORMS.map((p) => PLATFORM_SPECS[p].duration.mark), ['verified', 'verified', 'community', 'community', 'community', 'guidance']);
  eq('platform specs caps', PLATFORMS.map((p) => PLATFORM_SPECS[p].duration.cap), [null, 180, 600, 180, 140, 90]);
  eq('platform specs vertical flags', PLATFORMS.map((p) => PLATFORM_SPECS[p].aspects.vertical), [false, true, true, true, false, true]);
  // keep-span builder (tighten): margins, merging, min-keep, leading/trailing silence.
  const r1 = buildKeepSpans(20, [{ start: 10, end: 12 }], { margin: 0.15, minKeep: 0.2 });
  eq('keepspans margin keeps silence each side', r1.keep, [[0, 10.15], [11.85, 20]]);
  eq('keepspans one cut + removed total', [r1.cuts, r1.removedS], [1, 1.7]);
  eq('keepspans overlapping silences merge', buildKeepSpans(20, [{ start: 8, end: 10 }, { start: 9.5, end: 12 }], { margin: 0, minKeep: 0.2 }).keep, [[0, 8], [12, 20]]);
  // fadeJoin semantics: translate the ffmpeg expression (if/between) to JS and
  // evaluate it the way ffmpeg would (between inclusive, first-matching if-branch wins).
  {
    const between = (v, a, b) => v >= a && v <= b;
    const splitArgs = (s) => { const out = []; let d = 0; let cur = ''; for (const ch of s) { if (ch === '(') d++; if (ch === ')') d--; if (ch === ',' && d === 0) { out.push(cur); cur = ''; } else cur += ch; } out.push(cur); return out; };
    const toJs = (s) => {
      s = s.trim();
      if (s.startsWith('if(') && s.endsWith(')')) { const a = splitArgs(s.slice(3, -1)); return `(${toJs(a[0])} ? ${toJs(a[1])} : ${toJs(a[2])})`; }
      if (s.startsWith('between(') && s.endsWith(')')) { const a = splitArgs(s.slice(8, -1)); return `between(${a.map(toJs).join(',')})`; }
      return s;
    };
    const gainAt = (expr, t) => Function('t', 'between', `'use strict'; return (${toJs(expr)});`)(t, between);
    const j = fadeJoinExpr(10, 0.03);
    eq('fadejoin gain 1 far before the join', gainAt(j, 0), 1);
    eq('fadejoin gain 1 far after the join', gainAt(j, 20), 1);
    eq('fadejoin gain 0 at the join center', gainAt(j, 10), 0);
    eq('fadejoin gain ~1 at the outer edge before', Math.abs(gainAt(j, 10 - 0.03) - 1) < 1e-9, true);
    eq('fadejoin gain ~1 at the outer edge after', Math.abs(gainAt(j, 10 + 0.03) - 1) < 1e-9, true);
    eq('fadejoin gain ~0.5 at the ramp midpoints', Math.abs(gainAt(j, 10 - 0.015) - 0.5) < 1e-9 && Math.abs(gainAt(j, 10 + 0.015) - 0.5) < 1e-9, true);
    const j2 = fadeJoinExpr(20, 0.03);
    eq('fadejoin chained joins do not interfere', gainAt(j2, 0) * gainAt(j, 9.985) > 0.4, true); // join at 20 leaves join-at-10's window untouched
  }
  eq('parseVolumedetect max-only line', parseVolumedetect('max_volume: -91.0 dB').max, -91.0);
  eq('keepspans silence fully eaten by margins removes nothing', buildKeepSpans(20, [{ start: 10, end: 10.2 }], { margin: 0.15, minKeep: 0.2 }), { keep: [[0, 20]], cuts: 0, removedS: 0 });
  eq('keepspans null end means silent to EOF', buildKeepSpans(10, [{ start: 8, end: null }], { margin: 0.15, minKeep: 0.2 }).keep, [[0, 8.15]]);
  const tiny = buildKeepSpans(20, [{ start: 5, end: 5.4 }, { start: 5.6, end: 6 }], { margin: 0, minKeep: 0.25 });
  eq('keepspans drops keeps shorter than min-keep', tiny.keep, [[0, 5], [6, 20]]);
  eq('keepspans dropped keep merges its removals', tiny.cuts, 1);
  const edges = buildKeepSpans(20, [{ start: 0, end: 2 }, { start: 18, end: 20 }], { margin: 0.15, minKeep: 0.2 });
  eq('keepspans leading+trailing silence (margin keeps get dropped)', edges.keep, [[1.85, 18.15]]);
  eq('keepspans leading+trailing count 2 cuts', edges.cuts, 2);
  // threshold suggestion: mean + 6 dB, capped at -5.
  eq('suggest threshold mean+6', suggestThreshold(-20), -14);
  eq('suggest threshold caps at -5', suggestThreshold(-2), -5);
  eq('suggest threshold exactly at cap', suggestThreshold(-11), -5);
  eq('suggest threshold unknown mean', suggestThreshold(null), null);
  // keyframe bracketing (nearest_keyframes).
  eq('bracket keyframes middle', bracketKeyframes([0, 2, 4, 6], 3.1), { before: 2, after: 4 });
  eq('bracket keyframes exact hit', bracketKeyframes([0, 2, 4], 2), { before: 2, after: 2 });
  eq('bracket keyframes past end', bracketKeyframes([0, 2, 4], 10), { before: 4, after: null });
  eq('bracket keyframes before start', bracketKeyframes([2, 4], 1), { before: null, after: 2 });
  eq('bracket keyframes empty map', bracketKeyframes([], 5), { before: null, after: null });
  // volumedetect parser.
  eq('volumedetect parser', parseVolumedetect('[Parsed_volumedetect_0 @ 0x1] mean_volume: -23.4 dB | max_volume: -8.6 dB'), { mean: -23.4, max: -8.6 });
  eq('volumedetect parser rejects garbage', parseVolumedetect('nothing'), null);
  // atomic temp naming.
  eq('temp sibling name', tempSiblingName('out.mp4', 'abc123'), '.out.tmp-abc123.mp4');
  eq('temp sibling name unique per rand', tempSiblingName('out.mp4', 'a') !== tempSiblingName('out.mp4', 'b'), true);
  eq('temp sibling keeps the media extension', tempSiblingName('hook.mp4').endsWith('.mp4'), true);
  eq('temp sibling matches the cleanup pattern', TEMP_OUTPUT_RE.test(tempSiblingName('out.mp4')), true);
  // check-row builder on synthetic facts.
  const goodFacts = {
    file: 'hook_shorts_9x16-crop.mp4', duration: 58.2, width: 1080, height: 1920, fps: 30, vfr: false,
    videoCodec: 'h264', pixFmt: 'yuv420p', hasAudio: true, audioCodec: 'aac', audioSampleRate: 48000,
    faststart: true, loudness: { I: -14.2, TP: -2.1 }, silentAudio: false, audioMaxDb: -3.2, sizeBytes: 8 * 1024 * 1024,
  };
  const goodRows = buildCheckRows(goodFacts, { platform: 'shorts' });
  eq('check compliant file all PASS', goodRows.every((r) => r.status === 'PASS'), true);
  eq('check judgement kinds', goodRows.filter((r) => r.kind === 'judgement').map((r) => r.check).sort(), ['aspect', 'duration', 'loudness']);
  eq('check format kinds present', ['codec', 'faststart', 'pix_fmt', 'resolution', 'silent_audio'].every((c) => goodRows.some((r) => r.kind === 'format' && r.check === c)), true);
  const badFacts = { ...goodFacts, duration: 200, width: 640, height: 360 };
  const badRows = buildCheckRows(badFacts, { platform: 'shorts' });
  const durRow = badRows.find((r) => r.check === 'duration');
  const aspRow = badRows.find((r) => r.check === 'aspect');
  eq('check duration FAIL is judgement', [durRow.status, durRow.kind, durRow.reason], ['FAIL', 'judgement', 'duration 200s exceeds the 3-minute YouTube Shorts cap (verified)']);
  eq('check duration fix names the command', /^clipcut cut <source> --plan clips.json/.test(durRow.fix), true);
  eq('check aspect FAIL with crop fix', [aspRow.status, aspRow.kind, aspRow.fix], ['FAIL', 'judgement', 'clipcut export hook_shorts_9x16-crop.mp4 --platform shorts --variant 9x16-crop']);
  const noPlat = buildCheckRows(badFacts, {});
  const nd = noPlat.find((r) => r.check === 'duration');
  const na = noPlat.find((r) => r.check === 'aspect');
  eq('check without platform downgrades judgement rows', [nd.status, na.status], ['WARN', 'WARN']);
  eq('check without platform still has format rows enforcing', noPlat.filter((r) => r.kind === 'format').some((r) => r.check === 'codec'), true);
  const fsBad = buildCheckRows({ ...goodFacts, faststart: false }, { platform: 'shorts' }).find((r) => r.check === 'faststart');
  eq('check faststart FAIL stays FAIL without platform', [fsBad.status, fsBad.fix], ['FAIL', 'clipcut export hook_shorts_9x16-crop.mp4 --platform shorts --variant original']);
  const unmeasurableFacts = { file: 'x.mp4', duration: null, width: null, height: null, fps: null, vfr: false, videoCodec: null, pixFmt: null, hasAudio: false, audioCodec: null, audioSampleRate: null, faststart: null, loudness: null, silentAudio: null, audioMaxDb: null, sizeBytes: null };
  const unRows = buildCheckRows(unmeasurableFacts, { platform: 'shorts' });
  eq('check unmeasurable never PASS', unRows.some((r) => r.status === 'PASS'), false);
  eq('check unmeasurable all WARN with reason', unRows.every((r) => r.status === 'WARN' && /^could not measure/.test(r.reason)), true);
  const noAudio = buildCheckRows({ ...goodFacts, hasAudio: false, audioCodec: null, audioSampleRate: null, loudness: null, silentAudio: null }, { platform: 'shorts' });
  eq('check no-audio rows warn could not measure', noAudio.filter((r) => ['audio', 'audio_sample_rate', 'loudness', 'silent_audio'].includes(r.check)).every((r) => r.status === 'WARN' && r.reason.includes('could not measure')), true);
  const loudBad = buildCheckRows({ ...goodFacts, loudness: { I: -2, TP: 0.5 } }, { platform: 'shorts' }).find((r) => r.check === 'loudness');
  eq('check loudness extreme FAIL with loudnorm fix', [loudBad.status, loudBad.kind, loudBad.fix.includes('--loudnorm')], ['FAIL', 'judgement', true]);
  const loudBadNoPlat = buildCheckRows({ ...goodFacts, loudness: { I: -2, TP: 0.5 } }, {}).find((r) => r.check === 'loudness');
  eq('check loudness downgrades without platform', loudBadNoPlat.status, 'WARN');
  const silent = buildCheckRows({ ...goodFacts, silentAudio: true, audioMaxDb: -91 }, { platform: 'shorts' }).find((r) => r.check === 'silent_audio');
  eq('check silent audio FAIL', silent.status, 'FAIL');
  const vfrRow = buildCheckRows({ ...goodFacts, vfr: true }, { platform: 'shorts' }).find((r) => r.check === 'fps');
  eq('check vfr is a format WARN', [vfrRow.status, vfrRow.kind], ['WARN', 'format']);
  const oddRow = buildCheckRows({ ...goodFacts, width: 1081 }, { platform: 'shorts' }).find((r) => r.check === 'resolution');
  eq('check odd resolution FAIL format', [oddRow.status, oddRow.kind], ['FAIL', 'format']);
  // per-platform judgement classification: every platform yields judgement duration+aspect rows.
  eq('check all platforms classify duration/aspect judgement', PLATFORMS.every((p) => {
    const rs = buildCheckRows(goodFacts, { platform: p });
    return ['duration', 'aspect'].every((c) => { const r = rs.find((x) => x.check === c); return r && r.kind === 'judgement'; });
  }), true);
  const yt = buildCheckRows({ ...goodFacts, duration: 4000, width: 1920, height: 1080 }, { platform: 'youtube' });
  eq('check youtube long 16:9 passes duration', yt.find((r) => r.check === 'duration').status, 'PASS');
  eq('check youtube 16:9 aspect passes', yt.find((r) => r.check === 'aspect').status, 'PASS');
  const tt = buildCheckRows({ ...goodFacts, duration: 580 }, { platform: 'tiktok' }).find((r) => r.check === 'duration');
  eq('check tiktok 580s in the warn zone', tt.status, 'WARN');
  const ttOver = buildCheckRows({ ...goodFacts, duration: 650 }, { platform: 'tiktok' }).find((r) => r.check === 'duration');
  eq('check tiktok 650s WARN (community cap reported, not enforced)', [ttOver.status, ttOver.reason, ttOver.note.includes('reported, not enforced')], ['WARN', 'duration 650s may exceed community-reported TikTok upload limits (unverified; standard uploads allow up to ~10 min)', true]);
  // rotation: streamRotation parses the side_data_list Display Matrix entry; ±90/±270
  // swap width/height for display dims; 0/180/absent never swap.
  eq('streamRotation display matrix -90', streamRotation({ side_data_list: [{ side_data_type: 'Display Matrix', rotation: -90 }] }), -90);
  eq('streamRotation string value parses', streamRotation({ side_data_list: [{ side_data_type: 'Display Matrix', rotation: '270' }] }), -90);
  eq('streamRotation zero is null', streamRotation({ side_data_list: [{ side_data_type: 'Display Matrix', rotation: 0 }] }), null);
  eq('streamRotation absent is null', streamRotation({}), null);
  eq('streamRotation no list is null', streamRotation({ side_data_list: 'nope' }), null);
  eq('displayDims swap at -90', displayDimsForRotation(640, 360, -90), { width: 360, height: 640, rotated: true });
  eq('displayDims swap at 270', displayDimsForRotation(1920, 1080, 270), { width: 1080, height: 1920, rotated: true });
  eq('displayDims no swap at 180', displayDimsForRotation(640, 360, 180), { width: 640, height: 360, rotated: false });
  eq('displayDims no swap without rotation', displayDimsForRotation(640, 360, null), { width: 640, height: 360, rotated: false });
  eq('displayDims invalid width stays null (no swap)', displayDimsForRotation(0, 360, -90), { width: null, height: 360, rotated: false });
  // rotation-aware aspect: a coded 1920x1080 file with -90 rotation metadata DISPLAYS
  // 1080x1920 — PASS against a vertical platform with the rotation note (was a false FAIL).
  const rotFacts = { ...goodFacts, width: 1080, height: 1920, rotation: -90 };
  const rotRow = buildCheckRows(rotFacts, { platform: 'shorts' }).find((r) => r.check === 'aspect');
  eq('check aspect PASS on rotated file', [rotRow.status, /displays 1080x1920 after rotation metadata \(-90deg\)/.test(rotRow.note)], ['PASS', true]);
  const rotFacts2 = { ...goodFacts, width: 360, height: 640, rotation: -90 };
  const rotRow2 = buildCheckRows(rotFacts2, { platform: 'shorts' }).find((r) => r.check === 'aspect');
  eq('check rotated portrait aspect PASS note', [rotRow2.status, rotRow2.note.includes('displays 360x640 after rotation metadata')], ['PASS', true]);
  // resolution cap: informational judgement WARN (never FAIL) where the table marks a max.
  const overRes = buildCheckRows({ ...goodFacts, width: 1440, height: 2560 }, { platform: 'shorts' }).find((r) => r.check === 'resolution_cap');
  eq('check over-1080p shorts is judgement WARN', [overRes.status, overRes.kind, overRes.reason.includes('verified'), overRes.reason.includes('1440')], ['WARN', 'judgement', true, true]);
  const overResX = buildCheckRows({ ...goodFacts, width: 1440, height: 2560 }, { platform: 'x' }).find((r) => r.check === 'resolution_cap');
  eq('check over-1080p x is judgement WARN', [overResX.status, overResX.kind], ['WARN', 'judgement']);
  const overResTt = buildCheckRows({ ...goodFacts, width: 2160, height: 3840 }, { platform: 'tiktok' }).find((r) => r.check === 'resolution_cap');
  eq('check tiktok 4K informational WARN mentions compression', [overResTt.status, /4K uploads get compressed/.test(overResTt.reason)], ['WARN', true]);
  eq('check no resolution_cap row at/below cap', buildCheckRows(goodFacts, { platform: 'shorts' }).some((r) => r.check === 'resolution_cap'), false);
  eq('check youtube has no resolution_cap row', buildCheckRows({ ...goodFacts, width: 2160, height: 3840 }, { platform: 'youtube' }).some((r) => r.check === 'resolution_cap'), false);
  eq('check over-res needs a platform with a marked cap', buildCheckRows({ ...goodFacts, width: 1440, height: 2560 }, {}).some((r) => r.check === 'resolution_cap'), false);
  // loudness: quiet side is a WARN with the honest wording + loudnorm fix; only
  // clipping (TP>0) and over-loud (I>-2) hard-FAIL.
  const quiet = buildCheckRows({ ...goodFacts, loudness: { I: -30, TP: -20 } }, { platform: 'shorts' }).find((r) => r.check === 'loudness');
  eq('check quiet master WARN not FAIL', [quiet.status, quiet.reason.includes('no platform documents -14'), quiet.reason.includes('quiet master'), /--loudnorm$/.test(quiet.fix)], ['WARN', true, true, true]);
  const clip0 = buildCheckRows({ ...goodFacts, loudness: { I: -30, TP: 0.5 } }, { platform: 'shorts' }).find((r) => r.check === 'loudness');
  eq('check clipping TP>0 still FAILs', [clip0.status, clip0.reason.includes('clipping')], ['FAIL', true]);
  const overLoud = buildCheckRows({ ...goodFacts, loudness: { I: -1.5, TP: -3 } }, { platform: 'shorts' }).find((r) => r.check === 'loudness');
  eq('check over-loud I>-2 still FAILs', [overLoud.status, overLoud.reason.includes('over-loud')], ['FAIL', true]);
  const mildLoud = buildCheckRows({ ...goodFacts, loudness: { I: -6, TP: -2 } }, { platform: 'shorts' }).find((r) => r.check === 'loudness');
  eq('check mild loud-side deviation is WARN', mildLoud.status, 'WARN');
  const mildQuiet = buildCheckRows({ ...goodFacts, loudness: { I: -18, TP: -6 } }, { platform: 'shorts' }).find((r) => r.check === 'loudness');
  eq('check within 6 LU still PASS', mildQuiet.status, 'PASS');
  // size row: a cap with an unmeasurable size is a WARN, not an absent row.
  const sizeUnknown = buildCheckRows({ ...goodFacts, sizeBytes: null }, { platform: 'reels' }).find((r) => r.check === 'size');
  eq('check size unknown under a cap is WARN', [sizeUnknown.status, sizeUnknown.reason], ['WARN', 'could not measure (size unknown)']);
  eq('check size row absent without a cap', buildCheckRows({ ...goodFacts, sizeBytes: null }, { platform: 'shorts' }).some((r) => r.check === 'size'), false);
  // crop anchors: clean rejections outside [0,1]; byte-identical default filter; anchor math.
  const anchorMsg = (raw) => { try { cropAnchor(raw, 'crop-x'); return ''; } catch (e) { return e.message; } };
  eq('crop anchor rejects 1.5', /--crop-x must be a number between 0 and 1/.test(anchorMsg('1.5')), true);
  eq('crop anchor rejects -0.1', anchorMsg('-0.1') !== '', true);
  eq('crop anchor rejects junk', anchorMsg('middle') !== '', true);
  eq('crop anchor accepts 0 and 1', [cropAnchor('0', 'crop-x'), cropAnchor('1', 'crop-y')], [0, 1]);
  eq('crop anchor default when absent', [cropAnchor(null, 'crop-x'), cropAnchor(undefined, 'crop-y')], [0.5, 0.5]);
  eq('crop filter default anchors byte-identical', cropAnchorFilter(0.5, 0.5), "crop='min(iw,ih*9/16)':'min(ih,iw*16/9)',scale=1080:1920,setsar=1");
  eq('crop filter anchored right/bottom', cropAnchorFilter(1, 1), "crop='min(iw,ih*9/16)':'min(ih,iw*16/9)':'(iw-min(iw,ih*9/16))*1':'(ih-min(ih,iw*16/9))*1',scale=1080:1920,setsar=1");
  eq('crop filter anchored left/top', cropAnchorFilter(0, 0), "crop='min(iw,ih*9/16)':'min(ih,iw*16/9)':'(iw-min(iw,ih*9/16))*0':'(ih-min(ih,iw*16/9))*0',scale=1080:1920,setsar=1");
  eq('crop filter one-sided anchor keeps full expression', cropAnchorFilter(0.25, 0.5), "crop='min(iw,ih*9/16)':'min(ih,iw*16/9)':'(iw-min(iw,ih*9/16))*0.25':'(ih-min(ih,iw*16/9))*0.5',scale=1080:1920,setsar=1");
  // fingerprints: known-value hash anchors + window math + match logic.
  const SHA_EMPTY = 'e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855';
  const SHA_HELLO = '2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824';
  eq('sha256 known vector (empty)', sha256Hex(Buffer.alloc(0)), SHA_EMPTY);
  eq('sha256 known vector (hello)', sha256Hex(Buffer.from('hello')), SHA_HELLO);
  eq('headTailHash small buffer hashes whole twice', headTailHash(Buffer.from('hello')), `${SHA_HELLO}:${SHA_HELLO}`);
  eq('headTailHash empty buffer', headTailHash(Buffer.alloc(0)), `${SHA_EMPTY}:${SHA_EMPTY}`);
  eq('headTailHash window math (region 5 of 11 bytes)', headTailHash(Buffer.from('hello world'), 5), `${sha256Hex(Buffer.from('hello'))}:${sha256Hex(Buffer.from('world'))}`);
  eq('headTailHash window math (region 2 of 5 bytes)', headTailHash(Buffer.from('hello'), 2), `${sha256Hex(Buffer.from('he'))}:${sha256Hex(Buffer.from('lo'))}`);
  const fpTmp = path.join(os.tmpdir(), `clipcut-selftest-fp-${Date.now()}.bin`);
  fs.writeFileSync(fpTmp, Buffer.from('hello world'));
  const fp = fingerprintFile(fpTmp);
  fs.unlinkSync(fpTmp);
  eq('fingerprintFile size + head/tail pair', [fp.size, fp.sha256_head_tail], [11, `${sha256Hex(Buffer.from('hello world'))}:${sha256Hex(Buffer.from('hello world'))}`]);
  eq('fingerprintsMatch identical true', fingerprintsMatch(fp, { size: 11, sha256_head_tail: fp.sha256_head_tail }), true);
  eq('fingerprintsMatch size differs false', fingerprintsMatch(fp, { size: 12, sha256_head_tail: fp.sha256_head_tail }), false);
  eq('fingerprintsMatch hash differs false', fingerprintsMatch(fp, { size: 11, sha256_head_tail: `${SHA_HELLO}:${SHA_HELLO}` }), false);
  eq('fingerprintsMatch absent side null', fingerprintsMatch(fp, null), null);
  eq('fingerprintsMatch empty object null', fingerprintsMatch(fp, {}), null);
  // verify step-runner: fail flips the verdict and cascades skips with reasons.
  const vr = await runVerifySteps([
    { name: 'ok', fn: async () => {} },
    { name: 'skipped', fn: async () => ({ skip: 'because' }) },
    { name: 'boom', fn: async () => { throw new Error('boom'); } },
    { name: 'after', fn: async () => {} },
  ]);
  eq('verify runner rows classify', vr.rows.map((r) => [r.name, r.status]), [['ok', 'PASS'], ['skipped', 'SKIP'], ['boom', 'FAIL'], ['after', 'SKIP']]);
  eq('verify runner skip carries reason', vr.rows[1].reason, 'because');
  eq('verify runner fail carries reason', vr.rows[2].reason, 'boom');
  eq('verify runner cascade names the failed step', vr.rows[3].reason, 'earlier step failed: boom');
  eq('verify runner failed flag flips exit', vr.failed, true);
  const vrOk = await runVerifySteps([{ name: 'ok', fn: async () => ({ note: 'detail' }) }]);
  eq('verify runner all-pass is not failed', [vrOk.failed, vrOk.rows[0].note], [false, 'detail']);
  if (fails.length) { console.error(`\nselftest: ${fails.length} failure(s)`); return 2; }
  console.log('\nselftest: all checks passed');
  return 0;
}

// ---------------------------------------------------------------- help + dispatch

const HELP = `clipcut.mjs — cut long videos into social/creator clips: free local analysis first,
Cloudflare CLEF (decisions) + CLAIRIC (extraction) second, verified ffmpeg cutting and
platform export last.

Usage: node clipcut.mjs <command> [options]
Exit codes: 0 = pass/ok; 1 = attention needed (failed/escalated ratings, cut duration
errors, platform spec warnings, check FAIL rows); 2 = error (fix hint on stderr).

Pipeline: probe (free) -> segments (free) -> sheets (free) -> rate (CLEF, paid) ->
cut (free) -> tighten (free, optional) -> export (free) -> check (free, final gate)
-> preview (free). read (OCR/CLAIRIC) adds burned-in text. Typical loop: probe once,
segments+sheets, rate the sheets, keep the winners as a clips.json plan, then
cut/tighten/export/check/preview those. cut, export and tighten write their media
ATOMICALLY: a verified hidden temp file is renamed over the output only after it
passes a post-write probe (duration / faststart box walk), so a failed encode never
replaces good output with a broken file. probe records a per-file fingerprint
(size + head/tail sha256) that cut can check (--strict refuses a swapped source).
verify <video> runs the whole local pipeline on a real file as a self-test.

Commands:
  doctor [--ping]
                       Node, env vars (set/missing + which file each came from), ffmpeg
                       (CLEFCUT_FFMPEG env -> @remotion/compositor-* -> PATH), OCR engines,
                       AI gateway. --ping adds ONE clef-flash question (the only network
                       call anywhere in doctor).
  probe <video> [--out probe.json] [--scene-threshold 0.4]
                       FREE, local only. Scene scores (ffmpeg select + metadata=print
                       written to a temp FILE — a 60-min video keeps FULL coverage),
                       silence map (silencedetect -35dB/0.5s), loudness (loudnorm JSON,
                       ebur128 fallback), keyframe timestamps (video packets with the K
                       flag; stdout pass, never truncated), container basics + a VFR
                       guess (r_frame_rate vs avg_frame_rate).
                       Output probe.json; --scene-threshold sets the scene-change cutoff.
  segments <probe.json> [--min 15] [--max 90] [--count 10] [--even-split N] [--out segments.json]
                       FREE. Boundaries = union of scene_changes + silence ENDS (natural
                       cut points); from each boundary the longest boundary-delimited
                       segment fitting [min, max] becomes a candidate; a video shorter
                       than max is itself one candidate. Ranked by scene density x
                       loudness proximity, capped at --count, ids seg_001... in ranked
                       order. Each segment records signals: {scenes, silence_cut}.
                       segments.json also records the source {video, duration} so
                       sheets/read can warn on a mismatch. When NO candidate fits and the
                       video is longer than --max, exits 1 with guidance (lower --min /
                       re-probe with a lower --scene-threshold / use --even-split).
                       --even-split N skips the analysis: N equal segments flagged
                       "mechanical": true (honest equal divisions, not content picks).
  sheets <video> --segments segments.json [--out sheets/] [--frames 6]
                       FREE. Per segment: contact sheet PNG of --frames evenly-spaced
                       stills (~480px wide, tile 3x2 for 6, reading order) + a
                       sheets.json manifest. Existing --out may hold only seg_*.png +
                       sheets.json (cleared); anything else is an error.
  rate --sheets sheets/ --questions questions.json [--model clef-flash] [--gateway id]
        [--max-images 1] [--out ratings.json] [--yes]
                       CLEF pass over SHEETS. Default ONE image per request (per-segment
                       truth); set --max-images 2-4 to batch (a failing multi-image batch
                       is auto-isolated and re-asked one image per request). The sheet
                       list comes from the sheets.json manifest ONLY — never a PNG glob
                       (a crashed sheets run leaves partials; missing/empty manifest is a
                       clean error). Credentials
                       are checked BEFORE anything is read or sent; the cost estimate
                       prints before the first request; more than 240 images needs --yes
                       (or CLEFCUT_YES=1). requests are paced >= 300 ms apart and
                       ratings.json is rewritten after every request ("complete": false
                       until the run finishes; a fatal mid-run error still leaves the
                       partial file, then exits 2). Exit 1 when any segment fails or
                       escalates ("attention needed").
  read <video|sheetsDir> --segments segments.json [--engine local|clairic|auto]
       [--fields fields.json] [--out text.json] [--yes]
                       Burned-in text per segment. For a video input the MIDDLE frame of
                       each segment is extracted once, scaled to at most 1280px wide
                       (never upscaled — bounds tokens/bytes); a sheets dir uses the
                       sheets via their manifest. The model is told WHAT it sees: a
                       contact sheet (sheets dir) or a single midpoint frame (video).
                       --engine is chosen ONCE per run and reported: local = tesseract.js
                       or system tesseract (tesseract.js downloads English traineddata on
                       its first run; on an airgapped machine install system tesseract
                       instead); clairic = Cloudflare extraction, 1 image per request,
                       credentials BEFORE any frame extraction, same cost gate / pacing /
                       incremental writes as rate; auto = local when available, else
                       clairic. Default field: {"onscreen_text": {"type": "text"}}.
  cut <video> --plan clips.json [--mode lossless|accurate] [--tolerance 0.5] [--outdir clips/] [--strict]
                       The source is probed and the plan validated BEFORE any previous
                       output is cleared — a corrupt source never empties --outdir. The
                       dir may hold earlier tool-named clip outputs (<slug>.mp4 and the
                       <slug>_<platform>_<variant>.mp4 family): only the stale report is
                       cleared upfront; clips are replaced by ATOMIC verified writes.
                       FINGERPRINT: when the plan carries one (copied from probe.json's
                       "fingerprint": size + head/tail sha256), it is compared to the
                       actual file — a mismatch (same path/duration, different bytes)
                       prints a loud warning; --strict turns it into exit 2 BEFORE any
                       cutting. Lossless first: -ss before -i + -c copy +
                       -avoid_negative_ts make_zero, then the ACTUAL output duration is
                       measured with ffprobe; when the error exceeds --tolerance
                       (seconds) OR the source is VFR, the clip is re-encoded accurately
                       (libx264 crf 18, yuv420p, aac 192k, faststart) with 30 ms audio
                       fades (accurate mode always re-encodes and always fades).
                       cut-report.json records file, mode (copy/re-encode), requested_s,
                       actual_s, duration_error_ms, start_error_ms (copy mode only:
                       requested start vs the keyframe actually used), av_start_skew_s
                       (copy mode with audio only: first video pts vs first audio pts;
                       over max(2 frames, 0.1s) also sets av_start_skew_warning — a
                       WARNING field, it does not change exit semantics) and the exact
                       command per clip. Re-encoded cuts additionally record
                       nearest_keyframes {before, after} (the keyframes bracketing the
                       requested start) and lossless_alternative {command, reason} — the
                       -c copy command that WOULD have run and why it did not (e.g.
                       "keyframe snap 1200ms exceeds tolerance 500ms"). Exit 1 when any
                       clip is still over tolerance at the end (failing slugs listed).
  tighten <clip> [--threshold -35] [--min-silence 0.6] [--margin 0.15] [--min-keep 0.2]
         [--max-cuts 400]
                       Silence removal for a cut clip — make it punchy. Silences are
                       detected on the audio track (silencedetect; --threshold in dBFS,
                       --min-silence in s); --margin s of silence stays attached to each
                       side of kept speech so joins sound natural; kept pieces shorter
                       than --min-keep are dropped; more than --max-cuts cuts is
                       refused with guidance to raise --min-silence (the select filter
                       graph would be oversized). ONE re-encode (crf 18 / medium /
                       yuv420p / aac 192k / +faststart) with 30 ms audio fades at every
                       join. Output <stem>_tight.mp4, written atomically; report line:
                       before_s / after_s / removed_s / cuts. When no silence is found
                       the track mean level is measured and a suggested --threshold is
                       printed (mean + 6 dB, capped at -5 dB) — exit 0 ("nothing to
                       tighten"). AUDIO ROUTE: direct aselect, verified empirically on
                       ffmpeg 9.0.2 (kajisho5/ffmpeg-skill reports 8/8.1 builds pass
                       everything through) — the atomic post-write duration check
                       catches such a build and writes nothing.
  export <clip> --platform youtube|shorts|tiktok|reels|x|creator
         [--variant original|9x16-crop|9x16-blur] [--crop-x 0.5] [--crop-y 0.5]
         [--loudnorm] [--out exports/]
                       original: ensure the shared platform baseline — faststart + even
                       dimensions + h264/yuv420p (stream-copy remux when already
                       compliant; re-encode crf 18 when odd, non-H.264 or non-yuv420p). 9x16-crop:
                       crop='min(iw,ih*9/16)':'min(ih,iw*16/9)',scale=1080:1920,setsar=1
                       — a bounded crop, so ANY aspect (portrait/taller-than-9:16,
                       landscape, square) fills 1080x1920. --crop-x/--crop-y (0..1,
                       default 0.5) ANCHOR the crop window in the leftover region:
                       x=(iw-out_w)*crop-x, y=(ih-out_h)*crop-y — 0 pins the window to
                       the left/top edge, 1 to the right/bottom edge, 0.5 is the exact
                       historical center crop. Anchors apply to 9x16-crop only (clean
                       error elsewhere). 9x16-blur: blurred cover
                       background + centered foreground; a source taller than 9:16 gets
                       a warning that vertical content is cropped. All re-encode paths
                       add -movflags +faststart and yuv420p. --loudnorm runs a two-pass
                       loudnorm (pass 1 measures, pass 2 applies measured_*; target
                       I=-14 LUFS, TP=-1.5). Platform duration warnings come from the
                       SHARED platform table (same single source of truth as check):
                       shorts >180s (verified cap); tiktok >=570s, reels >180s,
                       x >140s (community-reported, unverified); creator >90s (generic
                       guidance); vertical platforms also warn when the output is not
                       9:16 (display dimensions — rotation metadata honored); youtube
                       has no duration warn. The output is written
                       atomically (verified temp, then rename). Exit 1 on any platform
                       warning. Output name: <slug>_<platform>_<variant>.mp4.
  check <file> [--platform youtube|shorts|tiktok|reels|x|creator] [--out check-report.json]
                       Compliance verification — the final gate after export. Rows:
                       duration, aspect (rotation-aware: display dimensions after
                       rotation metadata, so a tkhd-rotated file is judged by what it
                       shows), resolution (divisible-by-2), resolution_cap
                       (informational WARN when the short side exceeds the max the
                       platform's row marks — shorts 1080p verified, x 1080p and
                       tiktok "4K compressed" community; never a hard gate), fps +
                       VFR/CFR, codec, pix_fmt, audio presence/codec, sample rate,
                       faststart (moov-box walk), loudness (measure-only I/TP; FAIL
                       only for clipping TP>0 or over-loud I>-2 LUFS — a QUIET master
                       is a WARN with the loudnorm fix), silent audio, and size where
                       the shared table carries a cap (unmeasurable size = WARN
                       "could not measure (size unknown)", never an absent row). Each
                       row is PASS/WARN/FAIL with kind "format"|"judgement"
                       (duration/aspect/loudness are judgement), a plain-language
                       reason when not PASS, and a fix naming the exact clipcut
                       command when one exists (e.g. "clipcut export <file>
                       --platform shorts --variant 9x16-crop", "clipcut tighten
                       <file>"). UNMEASURABLE facts (probe fails, no audio stream,
                       silent track) are WARN "could not measure" — never PASS.
                       Without --platform, judgement rows are evaluated against the
                       generic creator profile and downgrade to WARN; format rows
                       still enforce. Any FAIL exits 1. Writes check-report.json + a
                       human summary.
  preview <clip> [--source <video> --start S --end E] [--probe probe.json] [--out preview/]
                       FREE, informational (exit 0 = ok, 2 = error). Writes
                       <slug>_preview.png (6-frame contact sheet), <slug>_3s.mp4 (first
                       3s) and <slug>_end3s.mp4 (last 3s) — samples muted, 320px wide.
                       With --source plus the clip's --start/--end it also BOUNDARY-
                       CHECKS both clip edges: a scene-score scan of the SOURCE over
                       [t-1.5, t+1.5] per edge records the max scene score in the
                       window and whether a scene change lands within 0.5s of the
                       boundary (--probe probe.json cross-checks its scene_changes).
                       Writes preview.json: {clip, file, samples: {sheet, first3s,
                       last3s}, boundaries: [{type: "start"|"end", t, window_s,
                       scene_score_max, scene_change_near}]}. The dir may hold ANY
                       slug's preview outputs; only this slug's files are replaced.
  plan [--file clips.json]
                       Print the clips.json schema + a minimal example; with --file,
                       validate the file, print each clip's duration and the total
                       (0 valid, 1 warnings only, 2 invalid). Unknown platform ids are
                       an open list: they map to the generic creator profile with a
                       warning, not an error.
  verify <video> [--net]
                       Real-footage self-test: runs the REAL pipeline commands on the
                       user's own file — probe (incl. fingerprint) -> segments (>=1
                       candidate, or a clean SKIP reason on a <15s file) -> sheets ->
                       cut a short slice from the first segment (duration_error_ms
                       reported) -> tighten on the slice (SKIP with a reason when it
                       has no audio / no silence) -> export 9x16-crop with the default
                       crop anchor (dims verified 1080x1920) -> check the export (WARNs
                       fine, FAILs fail the step) -> preview (files exist). Network
                       steps SKIP with "no credentials"/"pass --net" unless env
                       credentials exist AND --net is given — then ONE clef-flash ping
                       + ONE clairic image, cost gate respected. Per-step
                       PASS/FAIL/SKIP-with-reason + one summary line; exit 1 on any
                       FAIL. Everything runs in a temp dir under os.tmpdir() that is
                       ALWAYS cleaned — nothing touches the project. Run it once per
                       machine and after ffmpeg upgrades.
  --selftest           Built-in unit checks (no network, no ffmpeg needed).

questions.json schema (for rate) — identical to the sibling video-qa skill:
  {
    "questions": {
      "<id>": {
        "type": "noul" | "choice" | "score",
        "instructions": "...",            // required
        "criteria": { "opt": "desc" }     // choice: OBJECT (required)
        "criteria": ["ok", ..., "worst"]  // score: ordered ARRAY, worst LAST (required)
        "defect_options": ["opt"]         // choice, optional: options that mean "defect"
      }
    },
    "pass": { "<id>": 0.5 },              // REQUIRED for every id unless in escalate_only:
                                         // numeric, in (0,1]; defect-prob >= t => fail
    "escalate_margin": 0.3,               // defect-prob >= t - margin => escalate (default 0.3)
    "severity": { "<id>": "blocker" | "major" | "minor" },
    "escalate_only": ["<id>"]             // these ids never fail; fail becomes escalate
  }
  Defect probability: noul => answer.noul (yes = defect present);
  score => score / (levels-1) (highest level = worst);
  choice => probability of the question's "defect_options" (or 0 when absent).
  null/missing answers always escalate. Choice answers escalate when their OWN confidence
  is < 0.5 (fixed floor, never the pass threshold).

clips.json schema (for cut):
  {
    "video": "/abs/path/talk.mp4",       // optional: recorded source — cut warns when
                                         // the given video (or duration) differs
    "duration": 754.2,                   // optional: recorded source duration (seconds)
    "fingerprint": {                     // optional: copied from probe.json — cut
      "size": 12345,                     // compares it to the actual file and warns on
      "sha256_head_tail": "a..:b.."      // a mismatch; --strict refuses to cut (exit 2)
    },
    "clips": [
      {
        "slug": "hook",                    // required: filename-safe id [A-Za-z0-9._-], unique
        "start": 12.5,                     // required: seconds, >= 0
        "end": 58.2,                       // required: seconds, > start (5-600s recommended;
                                           //   a warning when end > the source duration)
        "variants": ["9x16-crop"],         // optional: original | 9x16-crop | 9x16-blur
        "platforms": ["shorts", "tiktok"]  // optional: open list — known ids ${PLATFORMS.join(' | ')};
                                           //   unknown ids map to the creator profile (warning)
      }
    ]
  }

fields.json schema (for read --engine clairic): {"<id>": {"type": "text", "instructions": "..."}}

Env: CLOUDFLARE_ACCOUNT_ID, CLOUDFLARE_API_TOKEN, CLEFCUT_GATEWAY_ID (optional),
CLEFCUT_FFMPEG/CLEFCUT_FFPROBE (optional), CLEFCUT_YES=1 (= --yes). Precedence: process env
> ./.env > ~/.clefcut/.env (doctor prints which file — or "process env" — each value came
from). Token values are never printed.

Examples:
  node clipcut.mjs doctor --ping
  node clipcut.mjs probe talk.mp4 --out probe.json
  node clipcut.mjs segments probe.json --min 15 --max 90 --count 10
  node clipcut.mjs sheets talk.mp4 --segments segments.json --out sheets/
  node clipcut.mjs rate --sheets sheets/ --questions questions.json
  node clipcut.mjs read talk.mp4 --segments segments.json --engine auto
  node clipcut.mjs cut talk.mp4 --plan clips.json --tolerance 0.5
  node clipcut.mjs tighten clips/hook.mp4
  node clipcut.mjs export clips/hook.mp4 --platform shorts --variant 9x16-crop --crop-x 1 --loudnorm
  node clipcut.mjs check exports/hook_shorts_9x16-crop.mp4 --platform shorts
  node clipcut.mjs preview clips/hook.mp4 --source talk.mp4 --start 12.5 --end 58.2
  node clipcut.mjs verify talk.mp4`;

/** Flags that must be followed by a value; a missing/true value is a clean exit-2 error. */
const VALUE_FLAGS = new Set(['out', 'scene-threshold', 'min', 'max', 'count', 'frames', 'sheets', 'segments', 'questions', 'fields', 'model', 'gateway', 'max-images', 'engine', 'plan', 'mode', 'tolerance', 'outdir', 'platform', 'variant', 'file', 'source', 'start', 'end', 'probe', 'even-split', 'threshold', 'min-silence', 'margin', 'min-keep', 'max-cuts', 'crop-x', 'crop-y']);

export function parseArgs(argv) {
  const out = { _: [] };
  for (let i = 0; i < argv.length; i++) {
    const a = argv[i];
    if (a === '--') { out._.push(...argv.slice(i + 1)); break; }
    if (a === '--help' || a === '-h') { out.help = true; continue; }
    if (a.startsWith('--')) {
      const key = a.slice(2);
      const next = argv[i + 1];
      if (next != null && !next.startsWith('--')) { out[key] = next; i++; }
      else out[key] = true;
      if (VALUE_FLAGS.has(key) && out[key] === true) throw new UserError(`--${key} requires a value`);
    } else out._.push(a);
  }
  return out;
}

function numFlag(o, key, dflt, { min, max } = {}) {
  if (o[key] == null || o[key] === true) return dflt;
  const n = Number(o[key]);
  const lo = min == null ? -Infinity : min;
  const hi = max == null ? Infinity : max;
  if (!Number.isFinite(n) || n < lo || n > hi) {
    const range = Number.isFinite(lo) && Number.isFinite(hi) ? ` between ${lo} and ${hi}` : Number.isFinite(lo) ? ` >= ${lo}` : ` <= ${hi}`;
    throw new UserError(`--${key} must be a number${range}. Got: ${o[key]}`);
  }
  return n;
}

async function main(argv) {
  try {
    const o = parseArgs(argv);
    if (o.selftest) return cmdSelftest();
    const cmd = o._[0];
    if (!cmd || o.help) { console.log(HELP); return 0; }
    switch (cmd) {
      case 'doctor': return await cmdDoctor(o);
      case 'probe': return await cmdProbe(o._[1], o);
      case 'segments': return await cmdSegments(o._[1], o);
      case 'sheets': return await cmdSheets(o._[1], o);
      case 'rate': return await cmdRate(o);
      case 'read': return await cmdRead(o._[1], o);
      case 'cut': return await cmdCut(o._[1], o);
      case 'tighten': return await cmdTighten(o._[1], o);
      case 'export': return await cmdExport(o._[1], o);
      case 'check': return await cmdCheck(o._[1], o);
      case 'preview': return await cmdPreview(o._[1], o);
      case 'verify': return await cmdVerify(o._[1], o);
      case 'plan': return cmdPlan(o);
      default: throw new UserError(`Unknown command: ${cmd}. Run with --help.`);
    }
  } catch (e) {
    if (e instanceof UserError) { console.error(`error: ${redact(e.message)}`); return 2; }
    console.error(`error: ${redact(e && e.stack ? e.stack : String(e))}`);
    return 2;
  }
}

// Symlink-safe: compare the REAL path of argv[1] (a symlink resolves to this file).
let invokedDirectly = false;
if (process.argv[1]) {
  try { invokedDirectly = pathToFileURL(fs.realpathSync(process.argv[1])).href === import.meta.url; } catch { /* unreadable argv[1] */ }
}
if (invokedDirectly) main(process.argv.slice(2)).then((code) => { process.exitCode = code; });

export {
  cmdDoctor, cmdProbe, cmdSegments, cmdSheets, cmdRate, cmdRead, cmdCut, cmdTighten, cmdExport, cmdCheck, cmdPreview, cmdPlan, cmdVerify,
  main,
};
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall