@officexapp/vidfarm-devcli 0.21.58 → 0.21.60

package/dist/src/devcli/proof-verify.js

@@ -0,0 +1,465 @@
+// `vidfarm gigs verify-proof` — the sanity check that runs BEFORE a proof is sent.
+//
+// A pending proof CAN be pulled back — `gigs withdraw` returns it to a draft —
+// but only until the buyer rules on it, and they open it days later in a swipe
+// deck, so in practice the first thing they see is the thing that decides it.
+// The two ways a finished video loses the payout are both mechanical, both land
+// before any undo would, and both are checkable from here:
+//
+//   1. THE LINK DOES NOT LOAD FOR THEM. It 403s because the s3 object was never
+//      made public, it answers an AccessDenied XML body with a 200-looking url,
+//      it is a presigned link whose read token expires in an hour, it is a
+//      Drive/Dropbox page behind a login, or it is http://localhost:8000 on the
+//      worker's own machine. Every one of those reads to a buyer as "no proof".
+//   2. THE TWO HALVES ARE SWAPPED. `proofs[]` is public — the buyer downloads it
+//      and so can anyone they forward it to. `private_note` is escrowed until a
+//      rollup stamps `paid_out_at`. Putting the clean master in `proofs[]` while
+//      the note holds nothing means the buyer has everything before paying.
+//
+// Check 1 is a HARD FAIL: there is no reading of the brief under which a dead
+// link is correct. Check 2 is a WARNING with an acknowledgement flag, because
+// handing the final cut over in the proof itself is a legitimate choice — it is
+// just one the worker has to make on purpose rather than by accident.
+//
+// Split shape-only rules (pure, no network) from the probe (one ranged GET per
+// url) so the rules stay unit-testable and an offline caller still gets most of
+// the value.
+//
+// Backend-free (Node built-ins + fetch) so it ships in the public cloud-only CLI.
+import { statSync } from "node:fs";
+const MEDIA_EXTENSIONS = new Set([
+    "mp4", "mov", "webm", "m4v", "mkv", "avi",
+    "mp3", "wav", "m4a", "aac", "ogg",
+    "png", "jpg", "jpeg", "webp", "gif", "avif"
+]);
+/** Hosts that answer a stranger with a sign-in page, not the file. */
+const LOGIN_WALLED = {
+    "drive.google.com": "Google Drive",
+    "docs.google.com": "Google Docs",
+    "www.dropbox.com": "Dropbox (a /scl or ?dl=0 link is a preview page)",
+    "dropbox.com": "Dropbox (a /scl or ?dl=0 link is a preview page)",
+    "wetransfer.com": "WeTransfer (and it expires)",
+    "we.tl": "WeTransfer (and it expires)",
+    "www.notion.so": "Notion",
+    "notion.so": "Notion",
+    "onedrive.live.com": "OneDrive",
+    "1drv.ms": "OneDrive",
+    "mega.nz": "MEGA",
+    "www.icloud.com": "iCloud"
+};
+/** Filenames that say this is the unwatermarked file. */
+const MASTER_NAME = /(clean|master|no[-_.]?water|unwatermark|nomark|raw[-_.]?final|final[-_.]?raw)/i;
+/**
+ * Pure url inspection: everything that can be decided from the string itself.
+ * No network, no side effects — this is the half that is unit-tested.
+ */
+export function inspectProofUrl(raw) {
+    const value = (raw ?? "").trim();
+    const empty = {
+        raw: value, valid: false, scheme: "", host: "", filename: "",
+        expiring: null, login_wall: null, private_host: false, looks_like_master: false
+    };
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        return empty;
+    }
+    const scheme = url.protocol.replace(":", "").toLowerCase();
+    const host = url.hostname.toLowerCase();
+    const filename = decodeURIComponent(url.pathname.split("/").filter(Boolean).pop() ?? "");
+    return {
+        raw: value,
+        valid: scheme === "http" || scheme === "https",
+        scheme,
+        host,
+        filename,
+        expiring: expiringToken(url),
+        login_wall: LOGIN_WALLED[host] ?? null,
+        private_host: isPrivateHost(host),
+        looks_like_master: MASTER_NAME.test(filename)
+    };
+}
+function isPrivateHost(host) {
+    if (host === "localhost" || host === "::1" || host.endsWith(".local") || host.endsWith(".localhost"))
+        return true;
+    if (/^127\./.test(host) || /^10\./.test(host) || /^192\.168\./.test(host))
+        return true;
+    if (/^172\.(1[6-9]|2\d|3[01])\./.test(host))
+        return true;
+    return false;
+}
+/**
+ * Signed, time-limited read access. The whole point of a proof url is that it
+ * still plays when the buyer gets round to the deck, so ANY of these is a fail
+ * even while it is still valid today.
+ */
+function expiringToken(url) {
+    const q = url.searchParams;
+    const has = (name) => q.has(name) || q.has(name.toLowerCase());
+    if (has("X-Amz-Signature") || has("X-Amz-Credential")) {
+        return { kind: "aws-sigv4 presigned", expires_in_seconds: amzRemaining(q) };
+    }
+    if (has("Key-Pair-Id") || (has("Signature") && has("Expires"))) {
+        const expires = Number(q.get("Expires") ?? q.get("expires"));
+        const remaining = Number.isFinite(expires) ? Math.round(expires - Date.now() / 1000) : null;
+        return { kind: "CloudFront signed", expires_in_seconds: remaining };
+    }
+    if (has("sig") && has("se"))
+        return { kind: "Azure SAS", expires_in_seconds: null };
+    if (has("GoogleAccessId") || has("X-Goog-Signature"))
+        return { kind: "GCS signed", expires_in_seconds: null };
+    return null;
+}
+/** `X-Amz-Date=20260825T120000Z` + `X-Amz-Expires=3600` → seconds left. */
+function amzRemaining(q) {
+    const date = q.get("X-Amz-Date") ?? q.get("x-amz-date");
+    const expires = Number(q.get("X-Amz-Expires") ?? q.get("x-amz-expires"));
+    if (!date || !Number.isFinite(expires))
+        return null;
+    const m = /^(\d{4})(\d{2})(\d{2})T(\d{2})(\d{2})(\d{2})Z$/.exec(date);
+    if (!m)
+        return null;
+    const signedAt = Date.UTC(Number(m[1]), Number(m[2]) - 1, Number(m[3]), Number(m[4]), Number(m[5]), Number(m[6]));
+    return Math.round((signedAt + expires * 1000 - Date.now()) / 1000);
+}
+/**
+ * Shape rules for one `proofs[]` url — the offline half of the check.
+ */
+export function shapeChecks(raw) {
+    const shape = inspectProofUrl(raw);
+    const checks = [];
+    const target = shape.raw || String(raw);
+    if (!shape.valid) {
+        checks.push({
+            level: "fail",
+            code: "not_a_url",
+            target,
+            message: "This is not an http(s) url, so the buyer's deck has nothing to play.",
+            hint: "Upload the file and submit the url it hands back: vidfarm gigs upload ./final-watermarked.mp4"
+        });
+        return checks;
+    }
+    if (shape.scheme === "http") {
+        checks.push({
+            level: "fail",
+            code: "insecure_scheme",
+            target,
+            message: "http:// is blocked as mixed content inside the review deck — the card stays blank.",
+            hint: "Serve the same file over https."
+        });
+    }
+    if (shape.private_host) {
+        checks.push({
+            level: "fail",
+            code: "private_host",
+            target,
+            message: `${shape.host} only exists on your own machine — nobody else can open it.`,
+            hint: "vidfarm gigs upload ./final-watermarked.mp4 puts it on a durable public url."
+        });
+    }
+    if (shape.login_wall) {
+        checks.push({
+            level: "fail",
+            code: "login_wall",
+            target,
+            message: `${shape.login_wall} serves a sign-in page to a stranger, not a playable file.`,
+            hint: "A proof must play inline with no account. Re-host it: vidfarm gigs upload <file>"
+        });
+    }
+    if (shape.expiring) {
+        const left = shape.expiring.expires_in_seconds;
+        const when = left === null ? "it expires on a clock" : left <= 0 ? "it has ALREADY expired" : `about ${Math.round(left / 3600)}h of read access is left`;
+        checks.push({
+            level: "fail",
+            code: "expiring_link",
+            target,
+            message: `${shape.expiring.kind} url — ${when}. Buyers review days later, so this dies before it is watched.`,
+            hint: "Submit a durable public url instead. A presigned url is for the UPLOAD, never for the proof."
+        });
+    }
+    return checks;
+}
+/**
+ * Container sniffing from the first bytes. The header lies often enough to be
+ * worth ignoring: a misconfigured bucket happily returns `video/mp4` on an
+ * AccessDenied XML body, and that is the exact failure this catches.
+ */
+export function sniffMagic(bytes) {
+    const at = (i) => bytes[i] ?? -1;
+    const ascii = (start, length) => String.fromCharCode(...Array.from(bytes.slice(start, start + length)));
+    if (bytes.length < 4)
+        return null;
+    if (ascii(4, 4) === "ftyp")
+        return "mp4";
+    if (at(0) === 0x1a && at(1) === 0x45 && at(2) === 0xdf && at(3) === 0xa3)
+        return "webm";
+    if (ascii(0, 4) === "RIFF")
+        return ascii(8, 4) === "WEBP" ? "webp" : "riff";
+    if (at(0) === 0x89 && ascii(1, 3) === "PNG")
+        return "png";
+    if (at(0) === 0xff && at(1) === 0xd8 && at(2) === 0xff)
+        return "jpeg";
+    if (ascii(0, 3) === "GIF")
+        return "gif";
+    if (ascii(0, 3) === "ID3")
+        return "mp3";
+    if (at(0) === 0xff && (at(1) & 0xe0) === 0xe0)
+        return "mp3";
+    if (ascii(0, 4) === "OggS")
+        return "ogg";
+    const head = ascii(0, Math.min(64, bytes.length)).trimStart().toLowerCase();
+    if (head.startsWith("<?xml") || head.startsWith("<html") || head.startsWith("<!doctype"))
+        return "markup";
+    return null;
+}
+/** Read at most `limit` bytes off a response, then drop the rest on the floor. */
+async function firstBytes(response, limit = 2048) {
+    if (!response.body)
+        return new Uint8Array(0);
+    const reader = response.body.getReader();
+    const chunks = [];
+    let total = 0;
+    while (total < limit) {
+        const { done, value } = await reader.read();
+        if (done || !value)
+            break;
+        chunks.push(value);
+        total += value.length;
+    }
+    await reader.cancel().catch(() => { });
+    const out = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+        out.set(chunk, offset);
+        offset += chunk.length;
+    }
+    return out.slice(0, limit);
+}
+/**
+ * One ranged GET, exactly as a stranger's browser would do it: no key, no
+ * cookie, follow redirects. A HEAD is not enough — plenty of buckets answer 200
+ * to a HEAD and an error body to a GET.
+ */
+export async function probeUrl(url, timeoutMs = 20000) {
+    const result = { url, ok: false, status: null, content_type: null, bytes: null, magic: null, error: null };
+    try {
+        const response = await fetch(url, {
+            method: "GET",
+            headers: { range: "bytes=0-2047" },
+            redirect: "follow",
+            signal: AbortSignal.timeout(timeoutMs)
+        });
+        result.status = response.status;
+        result.content_type = (response.headers.get("content-type") ?? "").split(";")[0].trim().toLowerCase() || null;
+        const range = response.headers.get("content-range");
+        const total = range ? Number(range.split("/").pop()) : Number(response.headers.get("content-length"));
+        result.bytes = Number.isFinite(total) ? total : null;
+        const head = await firstBytes(response);
+        result.magic = sniffMagic(head);
+        result.ok = response.ok;
+    }
+    catch (error) {
+        result.error = error?.name === "TimeoutError" ? "timed out after 20s" : String(error?.message ?? error);
+    }
+    return result;
+}
+/** Turn one probe into checks. Pure, so the verdict logic is testable. */
+export function probeChecks(probe) {
+    const checks = [];
+    const target = probe.url;
+    if (probe.error) {
+        checks.push({
+            level: "fail",
+            code: "unreachable",
+            target,
+            message: `The link did not load: ${probe.error}`,
+            hint: "Open it in a private browser window. If it needs your session, the buyer cannot watch it."
+        });
+        return checks;
+    }
+    if (probe.status !== null && !probe.ok) {
+        const why = probe.status === 403
+            ? "403 — uploaded, but the object is not readable by the public."
+            : probe.status === 404
+                ? "404 — nothing is at that key. The upload did not land where you think."
+                : `HTTP ${probe.status}.`;
+        checks.push({
+            level: "fail",
+            code: "http_status",
+            target,
+            message: `The buyer gets ${why}`,
+            hint: "vidfarm gigs upload <file> returns a url that is public by construction."
+        });
+        return checks;
+    }
+    if (probe.magic === "markup" || (probe.content_type ?? "").startsWith("text/html")) {
+        checks.push({
+            level: "fail",
+            code: "html_body",
+            target,
+            message: "That url answers a page, not a file — usually an S3 AccessDenied body or a sign-in wall.",
+            hint: "A deck card cannot play a web page. Submit the direct file url."
+        });
+        return checks;
+    }
+    if (probe.bytes === 0) {
+        checks.push({ level: "fail", code: "empty_body", target, message: "The file is 0 bytes — the upload did not finish." });
+        return checks;
+    }
+    const typeIsMedia = /^(video|audio|image)\//.test(probe.content_type ?? "");
+    if (!probe.magic && !typeIsMedia) {
+        checks.push({
+            level: "fail",
+            code: "not_media",
+            target,
+            message: `Neither the bytes nor the content-type (${probe.content_type ?? "none"}) look like a video, image or audio file.`,
+            hint: "The buyer swipes a deck and the card plays the first url inline."
+        });
+        return checks;
+    }
+    if (!typeIsMedia) {
+        checks.push({
+            level: "warn",
+            code: "octet_stream",
+            target,
+            message: `The bytes are a ${probe.magic} file but the server sends content-type "${probe.content_type ?? "none"}".`,
+            hint: "Some players refuse to inline that. Re-upload with the right content type."
+        });
+    }
+    if (probe.bytes !== null && probe.bytes > 0 && probe.bytes < 50_000) {
+        checks.push({
+            level: "warn",
+            code: "tiny_file",
+            target,
+            message: `Only ${probe.bytes} bytes. That is too small to be a finished cut.`
+        });
+    }
+    if (checks.length === 0) {
+        const size = probe.bytes === null ? "" : ` · ${(probe.bytes / 1_000_000).toFixed(1)} MB`;
+        checks.push({
+            level: "ok",
+            code: "playable",
+            target,
+            message: `Loads for a stranger: ${probe.magic ?? probe.content_type}${size}`
+        });
+    }
+    return checks;
+}
+/**
+ * The half that is a recommendation, not a law: watermark what is public, seal
+ * the master in the note. Warnings here, plus two genuine mistakes that fail.
+ */
+export function usageChecks(bundle) {
+    const checks = [];
+    const note = (bundle.privateNote ?? "").trim();
+    const hasMaster = Boolean(bundle.cleanMaster);
+    const noteUrls = note.match(/https?:\/\/\S+/g) ?? [];
+    const proofSet = new Set(bundle.proofs.map((p) => p.trim()));
+    if (bundle.cleanMaster) {
+        let size = -1;
+        try {
+            size = statSync(bundle.cleanMaster).size;
+        }
+        catch {
+            size = -1;
+        }
+        if (size < 0) {
+            checks.push({ level: "fail", code: "clean_master_missing", target: bundle.cleanMaster, message: "That clean-master file does not exist on disk." });
+        }
+        else if (size === 0) {
+            checks.push({ level: "fail", code: "clean_master_empty", target: bundle.cleanMaster, message: "The clean-master file is 0 bytes." });
+        }
+        else {
+            const ext = bundle.cleanMaster.toLowerCase().split(".").pop() ?? "";
+            if (!MEDIA_EXTENSIONS.has(ext)) {
+                checks.push({ level: "warn", code: "clean_master_not_media", target: bundle.cleanMaster, message: `".${ext}" is not a media extension — check you are sealing the video, not a note file.` });
+            }
+        }
+    }
+    // The sealed half points at the file you already published: the escrow is
+    // empty and the buyer has everything before paying.
+    const leaked = noteUrls.filter((u) => proofSet.has(u.replace(/[.,)]+$/, "")));
+    if (leaked.length) {
+        checks.push({
+            level: "fail",
+            code: "same_url_both_sides",
+            target: leaked[0],
+            message: "The private note points at a url you also submitted publicly, so the sealed half hands over nothing new.",
+            hint: "Seal the CLEAN master in the note and publish the WATERMARKED cut in --proof."
+        });
+    }
+    const duplicates = bundle.proofs.length - new Set(bundle.proofs).size;
+    if (duplicates > 0) {
+        checks.push({ level: "warn", code: "duplicate_proof_url", target: bundle.proofs[0] ?? "", message: "The same url is submitted more than once." });
+    }
+    if (!note && !hasMaster) {
+        if (bundle.cleanInProof) {
+            checks.push({
+                level: "ok",
+                code: "clean_in_proof_acknowledged",
+                target: "private_note",
+                message: "No private note, by your own choice — the proof url IS the final deliverable and the buyer holds it before payout."
+            });
+        }
+        else {
+            checks.push({
+                level: "warn",
+                code: "no_private_note",
+                target: "private_note",
+                message: "No private note. If that proof url is your unwatermarked final, the buyer has the whole job before paying for it.",
+                hint: "Recommended: --proof <watermarked url> --clean-master ./final-clean.mp4. Meant to hand it over? Pass --clean-in-proof."
+            });
+        }
+    }
+    else if (note && !hasMaster && noteUrls.length === 0) {
+        checks.push({
+            level: "warn",
+            code: "note_without_file",
+            target: "private_note",
+            message: "The private note is text only — it unseals on payment and the buyer receives no file from it.",
+            hint: "Put the clean master in it: --clean-master ./final-clean.mp4"
+        });
+    }
+    for (const url of bundle.proofs) {
+        const shape = inspectProofUrl(url);
+        if (shape.looks_like_master && (note || hasMaster)) {
+            checks.push({
+                level: "warn",
+                code: "master_name_in_proof",
+                target: url,
+                message: `"${shape.filename}" is named like the clean master, but you are also sealing one in the note.`,
+                hint: "Check you did not publish the unwatermarked cut by mistake — a proof url is public forever."
+            });
+        }
+    }
+    return checks;
+}
+/**
+ * Shape rules → one probe per url → the proof/note usage rules. `ok` is false
+ * whenever anything failed, which is what makes `verify-proof && gigs submit …`
+ * a real gate rather than a reminder.
+ */
+export async function verifyProof(bundle, options = {}) {
+    const checks = [];
+    const probes = [];
+    for (const url of bundle.proofs) {
+        const shape = shapeChecks(url);
+        checks.push(...shape);
+        // A url that is already condemned by its shape is not worth a round trip —
+        // and a localhost url would hang the check for the timeout.
+        if (shape.some((c) => c.level === "fail"))
+            continue;
+        if (options.probe === false)
+            continue;
+        const probe = await probeUrl(url, options.timeoutMs);
+        probes.push(probe);
+        checks.push(...probeChecks(probe));
+    }
+    checks.push(...usageChecks(bundle));
+    const failures = checks.filter((c) => c.level === "fail");
+    const warnings = checks.filter((c) => c.level === "warn");
+    return { ok: failures.length === 0, failures, warnings, checks, probes };
+}
+//# sourceMappingURL=proof-verify.js.map

package/dist/src/devcli/skill-docs.js

@@ -117,6 +117,8 @@ export const PACK_TOPICS = [
         blurb: "The 5-stage ladder — what the viewer knows, what the video must do, and what it may ask for" },
     { topic: "problem-angles", aliases: ["angle", "lenses", "problem-angle"], doc: "references/content-ideas.md", heading: "The problem angles",
         blurb: "44 angles on the problem — hold the frame, change the angle when a topic is \"already covered\"" },
+    { topic: "ad-formats", aliases: ["ad-format", "formats", "format", "executions"], doc: "references/content-ideas.md", heading: "The ad formats",
+        blurb: "40 ad formats — what the finished video IS (iphone notes, tier list, trustpilot reviews, warning), and the honesty rule for the ones that imitate a record" },
     { topic: "meme-recaption", // `meme_recaption` needs no alias: resolvePackTopic folds `_` to `-` first.
         aliases: ["meme", "recaption", "meme-caption"], doc: "references/editor-workflows.md", heading: "Writing a meme recaption",
         blurb: "Recaption a meme at a pain or a win the niche knows — the cold-viewer test. Building one from scratch? the full format is vidfarm.cc/experimental/meme-recaption.md" },
@@ -248,6 +250,18 @@ export function loadAngleBank(name = DEFAULT_PACK) {
     const { frames, families } = parseBulletBank(contents, "The problem angles", true);
     return { angles: frames, families };
 }
+/**
+ * The ad-format bank — the FOURTH axis. A frame says what the video is the
+ * story of and an angle says which side of the problem it comes from; a format
+ * says what the finished thing IS (an iPhone note, a tier list, a warning
+ * label). Left unnamed, a director shoots the same talking head all month, so
+ * it belongs next to the other banks rather than in the prose nobody reads.
+ */
+export function loadAdFormatBank(name = DEFAULT_PACK) {
+    const { contents } = readPackDoc("references/content-ideas.md", name);
+    const { frames, families } = parseBulletBank(contents, "The ad formats", true);
+    return { formats: frames, families };
+}
 export function loadAwarenessLadder(name = DEFAULT_PACK) {
     const { contents } = readPackDoc("references/content-ideas.md", name);
     const section = extractSection(contents, "The awareness ladder");