@vfrey/vfrey 1.0.0-beta.0 → 1.0.0-beta.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vfrey/vfrey",
-  "version": "1.0.0-beta.0",
+  "version": "1.0.0-beta.1",
   "type": "module",
   "description": "vfrey worker. Generate, render, publish, engage, and collect metrics.",
   "license": "SEE LICENSE IN LICENSE",
@@ -52,7 +52,7 @@
     "yauzl": "3.4.0"
   },
   "optionalDependencies": {
-    "@esbuild/linux-x64": "0.28.1",
+    "@esbuild/linux-x64": "0.28.2",
     "@remotion/compositor-linux-x64-gnu": "4.0.537",
     "@rollup/rollup-linux-x64-gnu": "4.64.12",
     "@rspack/binding-linux-x64-gnu": "1.7.11"

package/skills/vfrey-product/SKILL.md

@@ -20,7 +20,7 @@ The person asks in plain language; you run `npx vfrey`. Everything lives in a pr
 - "show me", "open the dashboard", "where is my video": `npx vfrey open [run id | video title or path]` (reuses the project's dashboard or starts it, prints the URL; `--no-browser` only prints). Never start the dashboard any other way.
 - "my videos": `npx vfrey videos` (newest first, with paths); "my other projects": `npx vfrey projects`.
 - "what should I make", "trending in X": `npx vfrey topics --niche X` (ids: `topics niches`, free); cite the evidence, then `tick --now --about "<title>"`. Topics need an account and credits (`login`, `whoami`); a `✗`/`Fix:` says which is missing. "find creators / KOLs in X": `creators search --niche X` (Research plan). Outreach: draft with `npx vfrey mail draft`; NEVER approve or send unless the person says so for that specific draft; mail needs the Mail add-on.
-- "sign in", "my plan": `npx vfrey login` (prints a link and a code to relay) or `npx vfrey whoami`. Free features never need an account.
+- "sign in", "my plan": `npx vfrey login` (prints a link and a code to relay) or `npx vfrey whoami`. Free features never need an account. Team sync: `npx vfrey cloud link|push [--videos]|pull|status` (newest wins; the other copy is kept as `<file>.conflict-<time>`).
 - Old machine data, update, engines: `npx vfrey desk snapshot --json`, `npx vfrey update`, `npx vfrey engine list`. A run with `status: awaiting_review` waits for the person (series review on): tell them, then `npx vfrey desk job approve|reject --id <id> [--reason T]`. `npx vfrey --help` and `npx vfrey <command> --help` list the rest.
 
 ## Make a video
@@ -28,7 +28,7 @@ The person asks in plain language; you run `npx vfrey`. Everything lives in a pr
 You are the writer and the designer. vfrey has no model of its own; without your script the words are template filler, and without your scene the picture is a plain fallback.
 
 1. **Script.** Write `scripts/<idea>.json`: `{ "title", "hook", "lines": [...], "hashtags": [...] }` (`npx vfrey tick --script-template` prints one). 6 to 10 short spoken lines (4 to 12 allowed, at most 220 characters each), hook first, title at most 100 characters, 1 to 8 hashtags starting with `#`. Be accurate and plain: no invented statistics, numbers, quotes or sources; leave out what you are not sure of. Use the topic's key words (the quality check rejects a script that never mentions its subject). A bad file gets a `✗` line and a `Fix:` line; a rejected script prints its reason. Fix and rerun.
-2. **Scene.** Every idea gets its own picture ("what's the difference?", "3 facts", "how a mutex works" look different). There are no fixed templates: never reuse one scene for a new idea.
+2. **Scene.** Always design a scene for the idea (scene init, design, `--frame` preview, then tick with `--scene` and `--engine`). Use the default template only if the person explicitly asks for a quick text-only video, and say so. Every idea gets its own picture ("what's the difference?", "3 facts", "how a mutex works" look different). There are no fixed templates: never reuse one scene for a new idea.
    - `npx vfrey scene init scenes/<idea>` writes a commented starter (`index.html`; `--engine remotion` writes `index.tsx`). Replace it. Draw SVGs yourself and `<img>` them from the folder.
    - `index.html` renders with `vfrey-framey` (or `hyperframes`), `index.tsx` with `remotion`; a mismatch stops with a `Fix:` line. Always pass `--engine` with a scene.
    - vfrey supplies in `DIR/vfrey/` (rewritten at render, do not edit): `timing.json`, `voice.wav`, `vfrey.js`, local `gsap.min.js`, `fonts/fonts.css` (Titan One, JetBrains Mono, Google Sans Flex), `assets/` (stick figures `stick-*.svg`, glyphs `glyph-*.svg`).
@@ -46,7 +46,7 @@ You are the writer and the designer. vfrey has no model of its own; without your
    - `npx vfrey scene blocks [--category X]` lists them; `npx vfrey scene add BLOCK scenes/<idea>` copies one into the scene and prints the snippet to paste into `#root`.
    - Time it with `vfrey.block("#block-<name>", t)` inside `vfrey.onLine` or `vfrey.at`; mount each block once per scene; HTML scenes only. Placement, fit modes and restyling are in `scenes/blocks.md`.
 5. **Make it.** `npx vfrey tick --now --about "<subject>" --script scripts/<idea>.json --scene scenes/<idea> --engine vfrey-framey`. Subject goes in `--about` (no feed is read; it runs as its own job). Without `--about` the default series reads the Federal Reserve feed: say so and ask once for a topic. Leave `--script` out only if they say to let vfrey write it, and then say the words are generic. Never set `--dry-run` for a real video (it skips the file). `render --subject` is only a silent, untracked preview.
-6. **Tell them.** The summary has `✓ Video ready: <path>` (length and size from ffprobe: quote them), the transcript, the upload outcome, and `See it: http://127.0.0.1:<port>/runs/<id>` (live; the tick starts the dashboard). Relay the readable video path in `videos/` and the See it link; `npx vfrey open` shows it. Say `Scene: agent-written`; with the default template say so. `--json` has `{processed, jobs:[{id, series, status, mp4, transcript, durationSec, publish, engage, runUrl, scene, engine}]}`. Nothing made: the summary says why (`not due`, `paused`, `job <id> in progress` with its `npx vfrey desk job cancel --id <id>` fix). Never move or rename videos by hand; vfrey tracks the paths.
+6. **Tell them.** The summary has `✓ Video ready: <path>` (length and size from ffprobe: quote them), the transcript, the upload outcome, and `See it: http://127.0.0.1:<port>/runs/<id>`. That link is live because the tick starts the dashboard: relay it and the readable video path in `videos/` as they are, without hedging. Only if `curl` to it fails, run `npx vfrey open`. Say `Scene: agent-written`; with the default template say so. `--json` has `{processed, jobs:[{id, series, status, mp4, transcript, durationSec, publish, engage, runUrl, scene, engine}]}`. Nothing made: the summary says why (`not due`, `paused`, `job <id> in progress` with its `npx vfrey desk job cancel --id <id>` fix). Never move or rename videos by hand; vfrey tracks the paths.
 
 Voice is on (macOS `say`; `TTS_PROVIDER=openai` is the paid voice, `none` is silent). A machine without it stops with a `Fix:` line. No model key is needed. To check a dashboard link is live: `curl -s -o /dev/null -w "%{http_code}" <url>` expects `200`.
 

package/src/api/client.ts

@@ -14,6 +14,13 @@ import {
   type NicheRequestResponse,
   type NichesResponse,
   type TopicsResponse,
+  type CloudConfirmResponse,
+  type CloudFileDecl,
+  type CloudFileView,
+  type CloudPlanResponse,
+  type CloudProjectView,
+  type CloudPullResponse,
+  type CloudRunBody,
   type CreatorAlertsResponse,
   type CreatorProfileView,
   type CreatorSearchResponse,
@@ -124,6 +131,10 @@ export class ApiClient {
     if (status === 429 && err?.code === "rate_limited") {
       return new ApiFailure(message || "Too many requests.", "wait a minute and try again.", 429, "rate_limited");
     }
+    if (status === 429 && (err as { meter?: unknown } | null)?.meter === "storage") {
+      const url = err?.upgradeUrl ? clean(err.upgradeUrl, token) : "";
+      return new ApiFailure(message || "Your plan's cloud storage is full.", `free space (delete old videos from the cloud project) or ${url ? `upgrade at ${url}` : "upgrade your plan"}. Scenes and scripts are small; push without --videos.`, 429, "limit_reached");
+    }
     if (status === 429) {
       const resets = err?.resetsAt ? clean(err.resetsAt, token) : "";
       const url = err?.upgradeUrl ? clean(err.upgradeUrl, token) : "";
@@ -260,6 +271,74 @@ export class ApiClient {
     return this.request<OrgSwitchResponse>("POST", "/api/v1/orgs/switch", { orgId });
   }
 
+  // ---------- Hosted projects and sync (spec 019 B) ----------
+
+  cloudLink(body: { localProjectId: string; name: string }): Promise<{ project: CloudProjectView }> {
+    return this.request("POST", "/api/v1/cloud/projects", body);
+  }
+
+  cloudFiles(projectId: string): Promise<{ files: CloudFileView[] }> {
+    return this.request("GET", `/api/v1/cloud/projects/${encodeURIComponent(projectId)}/files`);
+  }
+
+  /** The diff: which of these files are new or changed, and a signed upload URL for each. */
+  cloudPlan(projectId: string, files: CloudFileDecl[]): Promise<CloudPlanResponse> {
+    return this.request("POST", `/api/v1/cloud/projects/${encodeURIComponent(projectId)}/files`, { files });
+  }
+
+  cloudConfirm(projectId: string, files: CloudFileDecl[]): Promise<CloudConfirmResponse> {
+    return this.request("POST", `/api/v1/cloud/projects/${encodeURIComponent(projectId)}/files/confirm`, { files });
+  }
+
+  cloudPushRuns(projectId: string, runs: CloudRunBody[]): Promise<{ runs: number }> {
+    return this.request("POST", `/api/v1/cloud/projects/${encodeURIComponent(projectId)}/runs`, { runs });
+  }
+
+  cloudPull(projectId: string, query: { since?: string | null; kinds?: string }): Promise<CloudPullResponse> {
+    const params = new URLSearchParams();
+    if (query.since) params.set("since", query.since);
+    if (query.kinds) params.set("kinds", query.kinds);
+    const qs = params.toString();
+    return this.request("GET", `/api/v1/cloud/projects/${encodeURIComponent(projectId)}/pull${qs ? `?${qs}` : ""}`);
+  }
+
+  /**
+   * One transfer to or from a signed storage URL. The vfrey token is NEVER sent here: the signed URL is the credential,
+   * and it may live on another host. https only (or this machine). Throws ApiFailure; no redirects.
+   */
+  async transfer(method: "PUT" | "GET", url: string, init: { headers?: Record<string, string>; body?: BodyInit; length?: number; timeoutMs?: number } = {}): Promise<Response> {
+    let target: URL;
+    try {
+      target = new URL(url);
+    } catch {
+      throw new ApiFailure("The server sent a storage link that is not a web address.", "update vfrey with `npx vfrey update`, or try again.");
+    }
+    const loopback = target.hostname === "localhost" || target.hostname === "127.0.0.1" || target.hostname === "[::1]";
+    if (target.protocol !== "https:" && !(target.protocol === "http:" && loopback)) {
+      throw new ApiFailure(`The storage link (${target.host}) is not https, so vfrey will not use it.`, "check the vfrey server's storage settings.");
+    }
+    const headers: Record<string, string> = { ...(init.headers ?? {}) };
+    delete headers.authorization;
+    delete headers.Authorization;
+    if (init.length !== undefined) headers["content-length"] = String(init.length);
+    let response: Response;
+    try {
+      response = await this.fetchFn(target.href, {
+        method,
+        headers,
+        ...(init.body !== undefined ? { body: init.body, duplex: "half" } : {}),
+        redirect: "error",
+        signal: AbortSignal.timeout(init.timeoutMs ?? 600_000),
+      } as RequestInit);
+    } catch {
+      throw new ApiFailure(`Could not reach the storage host ${target.host}.`, "check your connection and run the command again. Only what changed is sent.");
+    }
+    if (!response.ok) {
+      throw new ApiFailure(`Storage answered ${response.status} for a ${method === "PUT" ? "upload" : "download"}.`, response.status === 403 ? "the signed link expired; run the command again." : "run the command again. Only what changed is sent.", response.status);
+    }
+    return response;
+  }
+
   /** Revokes the calling token. */
   async revokeCurrentToken(): Promise<void> {
     const { status, json } = await this.send("DELETE", "/api/v1/tokens/current");

package/src/api/cloud-files.ts

@@ -0,0 +1,197 @@
+// The local side of `vfrey cloud` (spec 019 B): which files sync, hashing, the sync state, and safe writes.
+// The path rules here mirror the console's; the server checks them again, and pull checks what the server sends.
+import { createHash } from "node:crypto";
+import { createReadStream, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, renameSync, statSync, writeFileSync } from "node:fs";
+import path from "node:path";
+
+export type Kind = "scene" | "script" | "video" | "transcript" | "meta";
+
+export const MAX_TEXT_BYTES = 5 * 1024 * 1024;
+export const MAX_VIDEO_BYTES = 500 * 1024 * 1024;
+/** What one push may change, and how many files one request names (the server's caps). */
+export const MAX_PUSH_BYTES = 1024 * 1024 * 1024;
+export const MAX_FILES_PER_REQUEST = 200;
+
+const SCENE_EXT = new Set(["html", "htm", "css", "js", "mjs", "ts", "tsx", "jsx", "json", "svg", "png", "jpg", "jpeg", "webp", "gif", "woff", "woff2", "txt", "md"]);
+const SCRIPT_EXT = new Set(["json", "txt", "md"]);
+const VIDEO_EXT = new Set(["mp4", "webm"]);
+const TRANSCRIPT_EXT = new Set(["txt", "srt", "vtt"]);
+
+export type PathCheck = { ok: true; kind: Kind } | { ok: false; reason: string };
+
+/** Only relative paths under scenes/, scripts/ and videos/: no "..", no absolute path, no hidden or conflict files. */
+export function checkSyncPath(p: unknown): PathCheck {
+  if (typeof p !== "string" || p.length === 0) return { ok: false, reason: "empty path" };
+  if (p.length > 300) return { ok: false, reason: "path too long" };
+  // eslint-disable-next-line no-control-regex
+  if (/[\u0000-\u001f\u007f]/.test(p)) return { ok: false, reason: "control characters" };
+  if (p.includes("\\") || p.startsWith("/") || /^[A-Za-z]:/.test(p)) return { ok: false, reason: "not a relative path" };
+  const parts = p.split("/");
+  if (parts.some((x) => x === "" || x === "." || x === "..")) return { ok: false, reason: "empty, . or .. part" };
+  if (parts.some((x) => x.startsWith("."))) return { ok: false, reason: "hidden file" };
+  if (parts.some((x) => x.length > 120)) return { ok: false, reason: "name too long" };
+  if (p.includes(".conflict-")) return { ok: false, reason: "conflict copy" };
+  if (parts.length < 2) return { ok: false, reason: "outside scenes/, scripts/, videos/" };
+  const last = parts[parts.length - 1]!;
+  const ext = last.includes(".") ? last.split(".").pop()!.toLowerCase() : "";
+  if (parts[0] === "scenes") return SCENE_EXT.has(ext) ? { ok: true, kind: "scene" } : { ok: false, reason: `.${ext || "(none)"} is not a scene file type` };
+  if (parts[0] === "scripts") return SCRIPT_EXT.has(ext) ? { ok: true, kind: "script" } : { ok: false, reason: `.${ext || "(none)"} is not a script file type` };
+  if (parts[0] === "videos") {
+    if (VIDEO_EXT.has(ext)) return { ok: true, kind: "video" };
+    if (TRANSCRIPT_EXT.has(ext)) return { ok: true, kind: "transcript" };
+    if (ext === "json") return { ok: true, kind: "meta" };
+    return { ok: false, reason: `.${ext || "(none)"} is not a video or transcript file type` };
+  }
+  return { ok: false, reason: "outside scenes/, scripts/, videos/" };
+}
+
+export const maxBytes = (kind: Kind): number => (kind === "video" ? MAX_VIDEO_BYTES : MAX_TEXT_BYTES);
+
+export interface LocalFile {
+  path: string;
+  abs: string;
+  kind: Kind;
+  size: number;
+  sha256: string;
+  mtime: Date;
+}
+export interface Skipped {
+  path: string;
+  reason: string;
+}
+
+export function sha256File(file: string): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const hash = createHash("sha256");
+    createReadStream(file).on("data", (chunk) => hash.update(chunk)).on("error", reject).on("end", () => resolve(hash.digest("hex")));
+  });
+}
+
+/** Walks scenes/ and scripts/ (and videos/ with `videos`). Symlinks are never followed; anything that cannot sync is listed, not hidden. */
+export async function scanProject(root: string, opts: { videos: boolean }): Promise<{ files: LocalFile[]; skipped: Skipped[] }> {
+  const files: LocalFile[] = [];
+  const skipped: Skipped[] = [];
+  const roots = ["scenes", "scripts", ...(opts.videos ? ["videos"] : [])];
+  const walk = async (rel: string): Promise<void> => {
+    let entries;
+    try {
+      entries = readdirSync(path.join(root, rel), { withFileTypes: true });
+    } catch {
+      return;
+    }
+    entries.sort((a, b) => (a.name < b.name ? -1 : 1));
+    for (const entry of entries) {
+      const next = `${rel}/${entry.name}`;
+      if (entry.name.startsWith(".") || entry.name === "node_modules" || entry.name.includes(".conflict-")) continue;
+      if (entry.isSymbolicLink()) {
+        skipped.push({ path: next, reason: "symbolic link" });
+        continue;
+      }
+      if (entry.isDirectory()) {
+        await walk(next);
+        continue;
+      }
+      if (!entry.isFile()) continue;
+      const checked = checkSyncPath(next);
+      if (!checked.ok) {
+        skipped.push({ path: next, reason: checked.reason });
+        continue;
+      }
+      const abs = path.join(root, next);
+      const st = statSync(abs);
+      if (st.size > maxBytes(checked.kind)) {
+        skipped.push({ path: next, reason: `${Math.round(st.size / 1024 / 1024)} MB is over the ${Math.round(maxBytes(checked.kind) / 1024 / 1024)} MB limit for a ${checked.kind}` });
+        continue;
+      }
+      files.push({ path: next, abs, kind: checked.kind, size: st.size, sha256: await sha256File(abs), mtime: st.mtime });
+    }
+  };
+  for (const r of roots) {
+    const top = path.join(root, r);
+    if (existsSync(top) && lstatSync(top).isDirectory()) await walk(r);
+  }
+  return { files, skipped };
+}
+
+// ---------- sync state: what the cloud held the last time this machine pushed or pulled ----------
+
+export interface SyncState {
+  version: 1;
+  projectId: string;
+  cursor: string | null;
+  /** path -> sha256 the cloud held when this machine last saw it. */
+  files: Record<string, string>;
+}
+
+const stateFile = (root: string) => path.join(root, ".vfrey", "cloud-sync.json");
+
+export function readState(root: string, projectId: string): SyncState {
+  const fresh: SyncState = { version: 1, projectId, cursor: null, files: {} };
+  try {
+    const parsed = JSON.parse(readFileSync(stateFile(root), "utf8")) as Partial<SyncState>;
+    if (parsed.version !== 1 || parsed.projectId !== projectId || typeof parsed.files !== "object" || parsed.files === null) return fresh;
+    return { version: 1, projectId, cursor: typeof parsed.cursor === "string" ? parsed.cursor : null, files: { ...parsed.files } };
+  } catch {
+    return fresh;
+  }
+}
+
+export function writeState(root: string, state: SyncState): void {
+  mkdirSync(path.dirname(stateFile(root)), { recursive: true });
+  const tmp = `${stateFile(root)}.tmp`;
+  writeFileSync(tmp, JSON.stringify(state, null, 2) + "\n");
+  renameSync(tmp, stateFile(root));
+}
+
+// ---------- classification ----------
+
+export type Verdict = "same" | "new" | "push" | "pull" | "conflict";
+
+/**
+ * One file, three facts: its hash here, its hash in the cloud, and the hash the cloud had when we last synced.
+ * Changed only here -> push. Changed only in the cloud -> pull. Changed in both (or never synced and different) -> conflict.
+ */
+export function classify(local: string | undefined, cloud: string | undefined, base: string | undefined): Verdict {
+  if (local !== undefined && cloud === undefined) return "new";
+  if (local === undefined) return "pull";
+  if (local === cloud) return "same";
+  if (base === cloud) return "push";
+  if (base === local) return "pull";
+  return "conflict";
+}
+
+/** `<file>.conflict-<ISO time>`, with colons and dots made safe for every filesystem. A clash gets a counter. */
+export function conflictPath(abs: string, at: Date): string {
+  const stamp = at.toISOString().replace(/[:.]/g, "-");
+  let candidate = `${abs}.conflict-${stamp}`;
+  for (let n = 2; existsSync(candidate); n += 1) candidate = `${abs}.conflict-${stamp}-${n}`;
+  return candidate;
+}
+
+/**
+ * Where a path from the server lands, or an error. The path must pass the sync rules, stay inside the project root, and
+ * no part of it that exists may be a symbolic link (a link could send a write outside the project).
+ */
+export function safeTarget(root: string, rel: string): { ok: true; abs: string } | { ok: false; reason: string } {
+  const checked = checkSyncPath(rel);
+  if (!checked.ok) return { ok: false, reason: checked.reason };
+  let cur = root;
+  for (const part of rel.split("/")) {
+    cur = path.join(cur, part);
+    try {
+      if (lstatSync(cur).isSymbolicLink()) return { ok: false, reason: "a part of the path is a symbolic link" };
+    } catch {
+      break;
+    }
+  }
+  const abs = path.join(root, ...rel.split("/"));
+  if (path.relative(root, abs).startsWith("..") || path.isAbsolute(path.relative(root, abs))) return { ok: false, reason: "outside the project" };
+  return { ok: true, abs };
+}
+
+export function formatSize(n: number): string {
+  if (n >= 1024 ** 3) return `${(n / 1024 ** 3).toFixed(1)} GB`;
+  if (n >= 1024 ** 2) return `${(n / 1024 ** 2).toFixed(1)} MB`;
+  if (n >= 1024) return `${Math.round(n / 1024)} KB`;
+  return `${n} B`;
+}

package/src/api/cloud-runs.ts

@@ -0,0 +1,75 @@
+// Run metadata for `vfrey cloud push`: stages, checks and a publications summary from the project database.
+// Only summaries leave the machine: no script text, no tokens, no account secrets.
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { DatabaseSync } from "node:sqlite";
+import { storedVideoPath } from "../project/videos.js";
+import type { CloudRunBody } from "./types.js";
+
+const MAX_RUNS = 100;
+
+type Row = { id: string; stage: string; status: string; payload: string; created_at: string; finished_at?: string | null };
+type Payload = {
+  content?: { title?: unknown; outputPath?: unknown } | null;
+  rendered?: { durationSec?: unknown } | null;
+  checks?: unknown;
+  stages?: unknown;
+};
+
+const str = (v: unknown, max: number): string | null => (typeof v === "string" && v.trim() ? v.trim().slice(0, max) : null);
+
+/** The newest pipeline runs in `<dataDir>/pipeline.sqlite`. `videoPaths` are the project-relative videos that are (or just were) in the cloud: only those are named. */
+export function collectRuns(dataDir: string, root: string, videoPaths: ReadonlySet<string>): CloudRunBody[] {
+  const file = path.join(dataDir, "pipeline.sqlite");
+  if (!existsSync(file)) return [];
+  const db = new DatabaseSync(file, { readOnly: true });
+  try {
+    const rows = db.prepare(`SELECT * FROM jobs WHERE kind = 'pipeline' ORDER BY created_at DESC, id DESC LIMIT ${MAX_RUNS}`).all() as unknown as Row[];
+    const pubs = db.prepare(`SELECT platform, external_id, published_at, title FROM publications WHERE job_id = ? ORDER BY published_at`);
+    return rows.map((row) => {
+      let payload: Payload = {};
+      try {
+        payload = JSON.parse(row.payload) as Payload;
+      } catch {
+        payload = {};
+      }
+      const stored = payload.content?.outputPath;
+      let videoPath: string | null = null;
+      if (typeof stored === "string" && stored.endsWith(".mp4")) {
+        const rel = path.relative(root, storedVideoPath(dataDir, stored)).split(path.sep).join("/");
+        if (videoPaths.has(rel)) videoPath = rel;
+      }
+      const checks = (Array.isArray(payload.checks) ? payload.checks : []) as Array<Record<string, unknown>>;
+      const stages = Array.isArray(payload.stages) ? (payload.stages as Array<Record<string, unknown>>) : [{ stage: row.stage, status: row.status }];
+      const length = payload.rendered?.durationSec;
+      return {
+        localRunId: row.id,
+        title: str(payload.content?.title, 200),
+        status: row.status,
+        stage: row.stage,
+        startedAt: row.created_at,
+        finishedAt: row.finished_at ?? null,
+        durationSec: typeof length === "number" && Number.isFinite(length) ? length : null,
+        videoPath,
+        stages: stages.slice(0, 20).map((s) => ({ stage: str(s.stage, 60) ?? "", status: str(s.status, 40) ?? "", ...(str(s.at, 40) ? { at: str(s.at, 40)! } : {}) })),
+        checks: checks.slice(0, 100).map((c) => ({
+          id: str(c.id, 80) ?? "",
+          ...(str(c.phase, 20) ? { phase: str(c.phase, 20)! } : {}),
+          ...(str(c.severity, 20) ? { severity: str(c.severity, 20)! } : {}),
+          status: str(c.status, 20) ?? "",
+          ...(str(c.message, 300) ? { message: str(c.message, 300)! } : {}),
+          fix: str(c.fix, 300),
+          ...(typeof c.attempt === "number" ? { attempt: c.attempt } : {}),
+        })),
+        publications: (pubs.all(row.id) as Array<{ platform: string; external_id: string | null; published_at: string | null; title: string | null }>).slice(0, 20).map((p) => ({
+          platform: p.platform,
+          externalId: p.external_id,
+          publishedAt: p.published_at,
+          title: str(p.title, 200),
+        })),
+      };
+    });
+  } finally {
+    db.close();
+  }
+}