@officexapp/vidfarm-devcli 0.21.28 → 0.21.30

package/dist/src/devcli/qa-regime.js

@@ -0,0 +1,396 @@
+// QA_REGIME.md — a per-style quality contract for a template family.
+//
+// WHY IT EXISTS: `vidfarm qa`'s built-in rules are UNIVERSAL (no HTML slop, the
+// font regime, the thumbnail frame) — they are the same for every video anyone
+// makes, so they can live in code. A regime is the opposite: it is what makes
+// THIS director's THIS format good, and it changes per account, per offer, per
+// campaign. That can't be hard-coded, so it lives next to the work as Markdown
+// the director owns, edits, and versions.
+//
+// It matters most in SCRIPTING MODE. One video gets human eyes on every frame;
+// fifty variants generated in a loop do not. The regime is what a bulk run is
+// graded against — the thing that keeps variant #37 as good as variant #1.
+//
+// THE FORMAT is a plain Markdown doc with two machine-readable affordances:
+//
+//   1. Optional YAML-ish front matter with a `checks:` block. These are the
+//      assertions the CLI can settle DETERMINISTICALLY from the composition DOM
+//      (duration, aspect, hook word budget, banned phrases, …). No AI, no
+//      network, instant.
+//   2. Any `- [ ]` checkbox line anywhere in the body becomes a REVIEW ITEM:
+//      a question the CLI hands back for the agent (or the human) to answer.
+//      "Is the withheld answer one the viewer can't supply themselves?" is a
+//      judgment call; pretending a linter can settle it would be a lie.
+//
+// Everything else is prose the agent reads for context. That split is the whole
+// design: the CLI is honest about which half it can enforce, and it never
+// silently "passes" a video on the strength of the half it can't.
+//
+// COMPOSABLE BY CONSTRUCTION: regimes stack (`--regime a --regime b`), resolve
+// from a built-in name OR any path the user points at, and a directory's own
+// QA_REGIME.md is picked up automatically. Nothing here is a gate — same
+// feedback-not-a-gate contract as the rest of `vidfarm qa`.
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+const BUILTIN_SUFFIX = ".QA_REGIME.md";
+// ── Locating the built-in regimes ────────────────────────────────────────────
+// They ship inside the skill pack (.agents/skills/vidfarm/regimes/) rather than
+// as TS string constants, so a director can read, diff, and copy them as normal
+// files — the file IS the documentation.
+function builtinDir() {
+    let dir = path.dirname(fileURLToPath(import.meta.url));
+    for (let i = 0; i < 6; i += 1) {
+        const candidate = path.join(dir, ".agents", "skills", "vidfarm", "regimes");
+        if (existsSync(candidate))
+            return candidate;
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return null;
+}
+export function listBuiltinRegimes() {
+    const dir = builtinDir();
+    if (!dir)
+        return [];
+    return readdirSync(dir)
+        .filter((file) => file.endsWith(BUILTIN_SUFFIX))
+        .sort()
+        .map((file) => {
+        const full = path.join(dir, file);
+        const parsed = parseRegime(readFileSync(full, "utf8"), full);
+        return { name: file.slice(0, -BUILTIN_SUFFIX.length), path: full, video_type: parsed.video_type, summary: parsed.summary };
+    });
+}
+/** Resolve `hooks` (built-in) or `./my/QA_REGIME.md` (a path) to a file. */
+export function resolveRegimePath(ref) {
+    const direct = path.resolve(ref);
+    if (existsSync(direct) && !direct.endsWith(path.sep))
+        return direct;
+    const dir = builtinDir();
+    if (dir) {
+        const candidate = path.join(dir, `${ref}${BUILTIN_SUFFIX}`);
+        if (existsSync(candidate))
+            return candidate;
+    }
+    const names = listBuiltinRegimes().map((entry) => entry.name);
+    throw new Error(`No QA regime "${ref}". Pass a file path, or one of the built-ins: ${names.join(", ") || "(none bundled)"}. ` +
+        `Scaffold your own with \`vidfarm regime init <name> --out ./work/QA_REGIME.md\`.`);
+}
+/** A directory's own regime, if it has one. Case-tolerant on the filename. */
+export function discoverRegime(dir) {
+    for (const name of ["QA_REGIME.md", "qa_regime.md", "QA-REGIME.md"]) {
+        const candidate = path.join(dir, name);
+        if (existsSync(candidate))
+            return candidate;
+    }
+    return null;
+}
+/**
+ * A deliberately tiny front-matter reader: `key: value`, and one level of
+ * nesting under `checks:` with `- item` lists. We do NOT pull in a YAML parser —
+ * a regime that needs anchors and multi-document streams has stopped being a
+ * checklist a director maintains by hand.
+ */
+function parseFrontMatter(raw) {
+    const match = raw.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?/);
+    if (!match)
+        return { front: {}, body: raw };
+    const front = {};
+    let currentList = null;
+    let listKey = "";
+    let inChecks = false;
+    for (const line of match[1].split(/\r?\n/)) {
+        if (!line.trim() || line.trim().startsWith("#"))
+            continue;
+        const listItem = line.match(/^\s*-\s+(.*)$/);
+        if (listItem && currentList) {
+            currentList.push(listItem[1].trim().replace(/^["']|["']$/g, ""));
+            continue;
+        }
+        const pair = line.match(/^(\s*)([A-Za-z0-9_.-]+)\s*:\s*(.*)$/);
+        if (!pair)
+            continue;
+        const indented = pair[1].length > 0;
+        const key = pair[2];
+        const value = pair[3].trim();
+        if (currentList && !listItem) {
+            front[listKey] = currentList;
+            currentList = null;
+        }
+        if (key === "checks" && !value) {
+            inChecks = true;
+            continue;
+        }
+        if (!indented && key !== "checks")
+            inChecks = false;
+        const scopedKey = inChecks && indented ? `checks.${key}` : key;
+        if (!value) {
+            currentList = [];
+            listKey = scopedKey;
+            continue;
+        }
+        if (value.startsWith("[")) {
+            front[scopedKey] = value
+                .replace(/^\[|\]$/g, "")
+                .split(",")
+                .map((entry) => entry.trim().replace(/^["']|["']$/g, ""))
+                .filter(Boolean);
+            continue;
+        }
+        front[scopedKey] = value.replace(/^["']|["']$/g, "");
+    }
+    if (currentList)
+        front[listKey] = currentList;
+    return { front, body: raw.slice(match[0].length) };
+}
+const KNOWN_CHECKS = new Set([
+    "duration_sec", "aspect", "first_frame_visual", "first_frame_text", "hook_words_max",
+    "text_by_sec", "audio", "captions", "font_regime", "safe_zone", "forbid_text",
+    "require_text", "max_text_cards", "max_simultaneous_text", "scenes", "max_scene_sec"
+]);
+export function parseRegime(raw, source) {
+    const { front, body } = parseFrontMatter(raw);
+    const checks = {};
+    const unknown = [];
+    for (const [key, value] of Object.entries(front)) {
+        if (!key.startsWith("checks."))
+            continue;
+        const bare = key.slice("checks.".length);
+        if (KNOWN_CHECKS.has(bare))
+            checks[bare] = value;
+        else
+            unknown.push(bare);
+    }
+    const reviewItems = [];
+    let section = "Checklist";
+    for (const line of body.split(/\r?\n/)) {
+        const heading = line.match(/^#{1,6}\s+(.*)$/);
+        if (heading) {
+            section = heading[1].replace(/[*_`]/g, "").trim();
+            continue;
+        }
+        const bold = line.match(/^\*\*(.+?)\*\*\s*$/);
+        if (bold) {
+            section = bold[1].trim();
+            continue;
+        }
+        const box = line.match(/^\s*[-*]\s+\[( |x|X)\]\s+(.*)$/);
+        if (box)
+            reviewItems.push({ section, text: box[2].trim() });
+    }
+    const headline = body.split(/\r?\n/).find((line) => line.trim() && !line.startsWith("#") && !line.startsWith(">"));
+    const name = String(front.name ?? path.basename(source).replace(/\.md$/i, "").replace(/\.QA_REGIME$/i, ""));
+    return {
+        name,
+        source,
+        video_type: front.video_type ? String(front.video_type) : null,
+        summary: headline ? headline.replace(/[*_`]/g, "").trim().slice(0, 160) : null,
+        checks,
+        review_items: reviewItems,
+        unknown_check_keys: unknown
+    };
+}
+// ── Evaluating the deterministic half ────────────────────────────────────────
+function asList(value) {
+    if (!value)
+        return [];
+    return Array.isArray(value) ? value : [value];
+}
+/** `8-34` | `<=34` | `>=8` | `30` (exact-ish, ±0.5s). */
+function rangeSatisfied(spec, actual) {
+    const trimmed = spec.trim();
+    const between = trimmed.match(/^(-?[\d.]+)\s*-\s*(-?[\d.]+)$/);
+    if (between)
+        return actual >= Number(between[1]) - 0.001 && actual <= Number(between[2]) + 0.001;
+    const cmp = trimmed.match(/^(<=|>=|<|>)\s*(-?[\d.]+)$/);
+    if (cmp) {
+        const bound = Number(cmp[2]);
+        if (cmp[1] === "<=")
+            return actual <= bound + 0.001;
+        if (cmp[1] === ">=")
+            return actual >= bound - 0.001;
+        if (cmp[1] === "<")
+            return actual < bound;
+        return actual > bound;
+    }
+    const exact = Number(trimmed);
+    return Number.isFinite(exact) ? Math.abs(actual - exact) <= 0.5 : true;
+}
+function isRequired(value) {
+    return String(value ?? "").trim().toLowerCase() === "required";
+}
+function isForbidden(value) {
+    return String(value ?? "").trim().toLowerCase() === "forbidden";
+}
+export function evaluateRegime(parsed, facts) {
+    const checks = [];
+    const findings = [];
+    const where = `QA_REGIME "${parsed.name}"`;
+    const settle = (key, expected, actual, ok, fix) => {
+        checks.push({ key, expected, actual, ok });
+        if (!ok) {
+            findings.push({
+                rule: `regime:${key}`,
+                severity: "error",
+                message: `${parsed.name}: ${key} expects ${expected} — this composition is ${actual}.`,
+                where,
+                fix
+            });
+        }
+    };
+    const c = parsed.checks;
+    if (c.duration_sec !== undefined && facts.duration_sec !== null) {
+        const spec = String(c.duration_sec);
+        settle("duration_sec", spec, `${facts.duration_sec.toFixed(1)}s`, rangeSatisfied(spec, facts.duration_sec), "Retime the timeline (`vidfarm retime` / `vidfarm ripple`) or set the composition duration to land inside the regime's window.");
+    }
+    if (c.aspect !== undefined && facts.canvas.aspect) {
+        const allowed = String(c.aspect).split(/[|,]/).map((entry) => entry.trim());
+        settle("aspect", allowed.join(" or "), facts.canvas.aspect, allowed.includes(facts.canvas.aspect), "Resize the canvas (editor `set_composition canvas_width/canvas_height`) — a re-crop, not a re-render of the source.");
+    }
+    if (isRequired(c.first_frame_visual)) {
+        settle("first_frame_visual", "something on screen at t=0", facts.first_frame_visual ? "covered" : "black", facts.first_frame_visual, "Pull the opening clip to start:0 (`vidfarm retime <dir> --layer <key> --start 0`). Frame 0 is the thumbnail.");
+    }
+    if (c.first_frame_text !== undefined) {
+        const has = Boolean(facts.first_frame_text);
+        if (isRequired(c.first_frame_text)) {
+            settle("first_frame_text", "hook words up at t=0", has ? `"${facts.first_frame_text}"` : "no text at t=0", has, "Start the hook caption at 0 so the thumbnail states the promise before a word is spoken (muted autoplay is the default).");
+        }
+        else if (isForbidden(c.first_frame_text)) {
+            settle("first_frame_text", "no text at t=0", has ? `"${facts.first_frame_text}"` : "clean", !has, "Delay the first text layer past 0 — this regime wants the opening frame to carry the image alone.");
+        }
+    }
+    if (c.hook_words_max !== undefined) {
+        const budget = Number(c.hook_words_max);
+        const hook = facts.first_frame_text ?? facts.text_runs[0]?.text ?? "";
+        const words = hook ? hook.trim().split(/\s+/).length : 0;
+        if (Number.isFinite(budget) && hook) {
+            settle("hook_words_max", `≤${budget} words in the opening line`, `${words} ("${hook.slice(0, 48)}")`, words <= budget, "Cut the opening line to the shortest complete clause that still parses cold. Chunk 1 is read before any audio.");
+        }
+    }
+    if (c.text_by_sec !== undefined) {
+        const by = Number(c.text_by_sec);
+        const at = facts.first_text_at_sec;
+        if (Number.isFinite(by)) {
+            settle("text_by_sec", `text on screen by ${by}s`, at === null ? "no text at all" : `${at.toFixed(2)}s`, at !== null && at <= by + 0.001, "Move the first caption earlier. A muted viewer decides before the audio hook lands.");
+        }
+    }
+    if (c.audio !== undefined) {
+        if (isRequired(c.audio)) {
+            settle("audio", "at least one audio layer", `${facts.audio_layers}`, facts.audio_layers > 0, "Add narration or a bed (`vidfarm tts` free local voice, or `vidfarm media search --type bgm`).");
+        }
+        else if (isForbidden(c.audio)) {
+            settle("audio", "no audio layers", `${facts.audio_layers}`, facts.audio_layers === 0, "Remove the audio layers — this regime is for silent/overlay output.");
+        }
+    }
+    if (isRequired(c.captions)) {
+        settle("captions", "a caption run", `${facts.caption_layers} caption layer(s)`, facts.caption_layers > 0, "Generate captions (`vidfarm captions generate`) — three of the four charges reach a muted viewer through text.");
+    }
+    if (isRequired(c.font_regime)) {
+        settle("font_regime", "imported display fonts only", facts.off_regime_fonts.length ? facts.off_regime_fonts.join(", ") : "in regime", facts.off_regime_fonts.length === 0, "Coerce the off-regime families to Montserrat/TikTok Sans (`vidfarm set-style --font-family Montserrat`).");
+    }
+    if (isRequired(c.safe_zone) && facts.canvas.height && facts.canvas.width && facts.canvas.height > facts.canvas.width) {
+        // Position lives in the DOM style, so this reuses the built-in rule's intent
+        // rather than re-deriving it — the built-in check reports the offenders.
+        checks.push({ key: "safe_zone", expected: "8%–85% band (portrait)", actual: "see caption-safe-zone findings", ok: true });
+    }
+    for (const phrase of asList(c.forbid_text)) {
+        const hit = phrase && new RegExp(phrase.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"), "i").test(facts.all_text);
+        settle("forbid_text", `no "${phrase}" on screen`, hit ? `found "${phrase}"` : "absent", !hit, "Rewrite the line. The regime bans this phrasing for a reason recorded in the doc — read the section it sits under.");
+    }
+    for (const phrase of asList(c.require_text)) {
+        const hit = phrase && new RegExp(phrase.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"), "i").test(facts.all_text);
+        settle("require_text", `"${phrase}" appears on screen`, hit ? "present" : "missing", Boolean(hit), "Add the required line as a timed caption — this is usually a compliance or positioning beat the regime treats as mandatory.");
+    }
+    if (c.max_text_cards !== undefined) {
+        const max = Number(c.max_text_cards);
+        if (Number.isFinite(max)) {
+            settle("max_text_cards", `≤${max} standalone text cards`, `${facts.card_runs.length}`, facts.card_runs.length <= max, "Merge or drop cards. Standalone cards compete with the footage; captions carry the words instead.");
+        }
+    }
+    if (c.max_simultaneous_text !== undefined) {
+        const max = Number(c.max_simultaneous_text);
+        if (Number.isFinite(max)) {
+            settle("max_simultaneous_text", `≤${max} text runs at once`, `${facts.max_simultaneous_text}`, facts.max_simultaneous_text <= max, "Stagger the overlapping text layers. Two things to read at once means neither gets read.");
+        }
+    }
+    if (c.scenes !== undefined) {
+        const spec = String(c.scenes);
+        settle("scenes", `${spec} visual clips`, `${facts.visual_clips.length}`, rangeSatisfied(spec, facts.visual_clips.length), "Split or merge scenes to hit the regime's pacing shape (`vidfarm split` / `vidfarm retime`).");
+    }
+    if (c.max_scene_sec !== undefined) {
+        const max = Number(c.max_scene_sec);
+        const longest = facts.visual_clips.reduce((acc, clip) => Math.max(acc, clip.duration), 0);
+        if (Number.isFinite(max) && facts.visual_clips.length) {
+            settle("max_scene_sec", `no clip longer than ${max}s`, `longest is ${longest.toFixed(1)}s`, longest <= max + 0.001, "Cut the long clip or push a cutaway over it — a static hold past this length is where retention drops.");
+        }
+    }
+    for (const key of parsed.unknown_check_keys) {
+        findings.push({
+            rule: "regime:unknown-check",
+            severity: "warn",
+            message: `${parsed.name}: unknown check "${key}" — ignored (the CLI can't settle it).`,
+            where,
+            fix: `Known checks: ${[...KNOWN_CHECKS].join(", ")}. Anything else belongs in the prose/checklist half, where the agent judges it.`
+        });
+    }
+    return {
+        name: parsed.name,
+        source: parsed.source,
+        video_type: parsed.video_type,
+        checks,
+        review_items: parsed.review_items,
+        findings
+    };
+}
+export function loadAndEvaluateRegime(ref, facts) {
+    const file = resolveRegimePath(ref);
+    return evaluateRegime(parseRegime(readFileSync(file, "utf8"), file), facts);
+}
+/**
+ * Fold regime results into a QaReport. Regime failures are the DIRECTOR's own
+ * rules, so they land in the same errors list as the built-ins — but the verdict
+ * stays advisory: `vidfarm qa` still exits 0 unless the caller asked for
+ * --strict, exactly as it does for slop.
+ */
+export function mergeRegimeIntoReport(report, evaluations) {
+    const findings = evaluations.flatMap((evaluation) => evaluation.findings);
+    const errors = [...report.errors, ...findings.filter((finding) => finding.severity === "error")];
+    const warnings = [...report.warnings, ...findings.filter((finding) => finding.severity === "warn")];
+    return {
+        ...report,
+        ok: errors.length === 0,
+        verdict: errors.length ? "slop" : warnings.length ? "warnings" : "clean",
+        errors,
+        warnings,
+        regimes: evaluations
+    };
+}
+/** Human-readable regime block for the CLI (findings are printed by qa itself). */
+export function formatRegimeReport(evaluation, colors) {
+    const { green, red, dim, reset } = colors;
+    const lines = [];
+    const failed = evaluation.checks.filter((check) => !check.ok).length;
+    lines.push(`${dim}regime${reset} ${evaluation.name}${evaluation.video_type ? ` ${dim}(${evaluation.video_type})${reset}` : ""} ` +
+        `${dim}— ${evaluation.checks.length - failed}/${evaluation.checks.length} machine checks passed, ` +
+        `${evaluation.review_items.length} item(s) need your judgment${reset}`);
+    for (const check of evaluation.checks) {
+        const mark = check.ok ? `${green}✓${reset}` : `${red}✗${reset}`;
+        lines.push(`  ${mark} ${check.key} ${dim}expects ${check.expected} — got ${check.actual}${reset}`);
+    }
+    if (evaluation.review_items.length) {
+        lines.push(`  ${dim}Review items — answer each one honestly; the CLI cannot settle these:${reset}`);
+        let section = "";
+        for (const item of evaluation.review_items) {
+            if (item.section !== section) {
+                section = item.section;
+                lines.push(`    ${dim}${section}${reset}`);
+            }
+            lines.push(`      ${dim}[ ]${reset} ${item.text}`);
+        }
+    }
+    return lines.join("\n");
+}
+//# sourceMappingURL=qa-regime.js.map