@vfrey/vfrey 0.0.1 → 1.0.0-beta.1

package/src/api/client.ts

@@ -0,0 +1,361 @@
+// The one vfrey API client. Every paid command uses it: it adds the token, maps failures to the CLI's ✗ and Fix: lines,
+// and never prints the token.
+import {
+  CLI_CLIENT_ID,
+  isApiError,
+  type ApiError,
+  type DeviceCodeResponse,
+  type DeviceTokenErrorCode,
+  type DeviceTokenResponse,
+  type MeResponse,
+  type NicheRequestBody,
+  type OrgsResponse,
+  type OrgSwitchResponse,
+  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,
+  type MailDraftBody,
+  type MailDraftPatch,
+  type MailDraftView,
+  type MailIdentityBody,
+  type MailIdentityView,
+  type WatchlistItemView,
+  type WatchlistView,
+} from "./types.js";
+
+export type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
+
+/** A refusal the CLI prints as `✗ <message>` and `Fix: <fix>`. */
+export class ApiFailure extends Error {
+  constructor(message: string, readonly fix: string, readonly status?: number, readonly code?: string) {
+    super(message);
+  }
+}
+
+export interface ClientOptions {
+  baseUrl: string;
+  token?: string | null;
+  fetch?: FetchLike;
+  timeoutMs?: number;
+}
+
+const TOKEN_SHAPE = /vfr_[A-Za-z0-9_-]+/g;
+// eslint-disable-next-line no-control-regex
+const CONTROL = /[\u0000-\u001f\u007f-\u009f]/g;
+
+/** Text from the server, safe to print: no control characters (no terminal escapes), no token. */
+export function clean(text: unknown, token?: string | null): string {
+  let out = String(text ?? "").replace(CONTROL, " ").replace(TOKEN_SHAPE, "[token]");
+  if (token) out = out.split(token).join("[token]");
+  return out.trim();
+}
+
+const DEVICE_ERRORS = new Set<string>(["authorization_pending", "slow_down", "access_denied", "expired_token"]);
+
+export class ApiClient {
+  private readonly fetchFn: FetchLike;
+  private readonly timeoutMs: number;
+  readonly host: string;
+
+  constructor(private readonly options: ClientOptions) {
+    this.fetchFn = options.fetch ?? ((input, init) => fetch(input, init));
+    this.timeoutMs = options.timeoutMs ?? 15_000;
+    this.host = new URL(options.baseUrl).host;
+  }
+
+  private async send(method: string, path: string, body?: unknown): Promise<{ status: number; json: unknown; text: string }> {
+    const headers: Record<string, string> = { accept: "application/json" };
+    if (this.options.token) headers.authorization = `Bearer ${this.options.token}`;
+    if (body !== undefined) headers["content-type"] = "application/json";
+    let response: Response;
+    try {
+      response = await this.fetchFn(`${this.options.baseUrl}${path}`, {
+        method,
+        headers,
+        ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+        redirect: "error",
+        signal: AbortSignal.timeout(this.timeoutMs),
+      });
+    } catch (error) {
+      const timedOut = error instanceof Error && (error.name === "TimeoutError" || error.name === "AbortError");
+      throw new ApiFailure(
+        timedOut ? `${this.host} did not answer in ${Math.round(this.timeoutMs / 1000)} seconds.` : `Could not reach ${this.host}.`,
+        "check your connection and try again. Free features work without vfrey accounts.",
+      );
+    }
+    let text = "";
+    try {
+      text = await response.text();
+    } catch {
+      text = "";
+    }
+    let json: unknown = null;
+    try {
+      json = JSON.parse(text);
+    } catch {
+      json = null;
+    }
+    return { status: response.status, json, text };
+  }
+
+  /** Maps a non-2xx answer to the CLI's refusal. */
+  private fail(status: number, json: unknown, path = ""): ApiFailure {
+    const token = this.options.token;
+    const err = isApiError(json) ? (json as ApiError).error : null;
+    const message = err ? clean(err.message, token) : "";
+    if (status === 401) return new ApiFailure("You are not signed in, or this token was revoked.", "run `npx vfrey login`.", 401, "unauthorized");
+    if (status === 503 && err?.code === "capacity_paused") {
+      return new ApiFailure("vfrey is paused for new data right now.", "try again later. Cached results still work.", 503, "capacity_paused");
+    }
+    if (status === 402 && err?.code === "credits_required") {
+      const url = err.buyCreditsUrl ? clean(err.buyCreditsUrl, token) : "";
+      const need = typeof err.required === "number" ? ` It needs ${err.required} credits` : "";
+      const have = typeof err.balance === "number" ? `${need ? "; you have" : " You have"} ${err.balance}` : "";
+      const detail = need || have ? `${need}${have}.` : "";
+      return new ApiFailure(`${message || "Not enough credits."}${detail ? ` ${detail.trim()}` : ""}`, url ? `Buy credits: ${url}` : "buy credits on your vfrey billing page.", 402, "credits_required");
+    }
+    if (status === 402) {
+      const url = err?.upgradeUrl ? clean(err.upgradeUrl, token) : "";
+      return new ApiFailure(message || "This feature is not in your plan.", url ? `upgrade your plan at ${url}` : "upgrade your plan at your vfrey billing page.", 402, "plan_required");
+    }
+    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) : "";
+      const fix = resets ? `your limit resets at ${resets}${url ? `, or upgrade at ${url}` : ""}.` : "wait a little and try again.";
+      // The server names the meter when it can; otherwise the route says which one ran out.
+      const named = (err as { meter?: unknown } | null)?.meter;
+      const meter = typeof named === "string" && named ? clean(named, token)
+        : /^\/api\/v1\/(topics|niches)/.test(path) ? "topics.requests" : /^\/api\/v1\/creators\/(tiktok|instagram|youtube)\//.test(path) ? "creators.profiles" : "";
+      return new ApiFailure(`You reached this month's limit${meter ? ` for ${meter}` : ""}.`, fix, 429, err?.code ?? "limit_reached");
+    }
+    return new ApiFailure(message || `The vfrey server answered ${status}.`, status >= 500 ? "try again in a moment." : "run `npx vfrey doctor` and check the line above.", status, err?.code);
+  }
+
+  /** A JSON request. Throws ApiFailure for network trouble and any non-2xx answer. */
+  async request<T>(method: string, path: string, body?: unknown): Promise<T> {
+    const { status, json } = await this.send(method, path, body);
+    if (status < 200 || status >= 300) throw this.fail(status, json, path);
+    return json as T;
+  }
+
+  /** A request whose answer is plain text (a CSV export). Same refusals as `request`. */
+  async requestText(method: string, path: string): Promise<string> {
+    const { status, json, text } = await this.send(method, path);
+    if (status < 200 || status >= 300) throw this.fail(status, json, path);
+    return text;
+  }
+
+  /** Creator search (spec 017). Reads the server's index; costs credits. */
+  creatorSearch(query: Record<string, string>): Promise<CreatorSearchResponse> {
+    return this.request<CreatorSearchResponse>("GET", `/api/v1/creators/search?${new URLSearchParams(query).toString()}`);
+  }
+
+  creatorProfile(platform: string, handle: string): Promise<CreatorProfileView> {
+    return this.request<CreatorProfileView>("GET", `/api/v1/creators/${encodeURIComponent(platform)}/${encodeURIComponent(handle)}`);
+  }
+
+  creatorAlerts(): Promise<CreatorAlertsResponse> {
+    return this.request<CreatorAlertsResponse>("GET", "/api/v1/creators/alerts");
+  }
+
+  watchlists(): Promise<{ watchlists: WatchlistView[] }> {
+    return this.request("GET", "/api/v1/watchlists");
+  }
+
+  createWatchlist(name: string): Promise<{ id: string; name: string }> {
+    return this.request("POST", "/api/v1/watchlists", { name });
+  }
+
+  watchlistItems(id: string): Promise<{ watchlist: { id: string; name: string }; items: WatchlistItemView[] }> {
+    return this.request("GET", `/api/v1/watchlists/${encodeURIComponent(id)}/items`);
+  }
+
+  addWatch(id: string, body: { platform: string; handle: string }): Promise<{ ok: boolean; created: boolean }> {
+    return this.request("POST", `/api/v1/watchlists/${encodeURIComponent(id)}/items`, body);
+  }
+
+  removeWatch(id: string, platform: string, handle: string): Promise<{ ok: boolean }> {
+    return this.request("DELETE", `/api/v1/watchlists/${encodeURIComponent(id)}/items?${new URLSearchParams({ platform, handle }).toString()}`);
+  }
+
+  watchlistCsv(id: string): Promise<string> {
+    return this.requestText("GET", `/api/v1/watchlists/${encodeURIComponent(id)}/export.csv`);
+  }
+
+  // ---------- Mail (spec 018). Draft, approve and send are three separate calls; nothing here chains them. ----------
+
+  mailDraft(body: MailDraftBody): Promise<{ draft: MailDraftView }> {
+    return this.request("POST", "/api/v1/mail/drafts", body);
+  }
+
+  mailDrafts(query: { status?: string; limit?: number } = {}): Promise<{ drafts: MailDraftView[] }> {
+    const params = new URLSearchParams();
+    if (query.status) params.set("status", query.status);
+    if (query.limit) params.set("limit", String(query.limit));
+    const qs = params.toString();
+    return this.request("GET", `/api/v1/mail/drafts${qs ? `?${qs}` : ""}`);
+  }
+
+  mailGet(id: string): Promise<{ draft: MailDraftView }> {
+    return this.request("GET", `/api/v1/mail/drafts/${encodeURIComponent(id)}`);
+  }
+
+  mailEdit(id: string, patch: MailDraftPatch): Promise<{ draft: MailDraftView }> {
+    return this.request("PATCH", `/api/v1/mail/drafts/${encodeURIComponent(id)}`, patch);
+  }
+
+  mailApprove(id: string): Promise<{ draft: MailDraftView }> {
+    return this.request("POST", `/api/v1/mail/drafts/${encodeURIComponent(id)}/approve`, {});
+  }
+
+  mailSend(id: string): Promise<{ draft: MailDraftView }> {
+    return this.request("POST", `/api/v1/mail/drafts/${encodeURIComponent(id)}/send`, {});
+  }
+
+  mailDiscard(id: string): Promise<{ draft: MailDraftView }> {
+    return this.request("POST", `/api/v1/mail/drafts/${encodeURIComponent(id)}/discard`, {});
+  }
+
+  mailIdentity(): Promise<{ identity: MailIdentityView | null }> {
+    return this.request("GET", "/api/v1/mail/identity");
+  }
+
+  mailSaveIdentity(body: MailIdentityBody): Promise<{ identity: MailIdentityView; verificationEmailed: boolean }> {
+    return this.request("POST", "/api/v1/mail/identity", body);
+  }
+
+  /** Ranked topics for one niche. Costs credits on the server. */
+  topics(query: { niche: string; limit?: number; since?: string }): Promise<TopicsResponse> {
+    const params = new URLSearchParams({ niche: query.niche });
+    if (query.limit !== undefined) params.set("limit", String(query.limit));
+    if (query.since) params.set("since", query.since);
+    return this.request<TopicsResponse>("GET", `/api/v1/topics?${params.toString()}`);
+  }
+
+  niches(): Promise<NichesResponse> {
+    return this.request<NichesResponse>("GET", "/api/v1/niches");
+  }
+
+  requestNiche(body: NicheRequestBody): Promise<NicheRequestResponse> {
+    return this.request<NicheRequestResponse>("POST", "/api/v1/niches", body);
+  }
+
+  me(): Promise<MeResponse> {
+    return this.request<MeResponse>("GET", "/api/v1/me");
+  }
+
+  /** The orgs this user belongs to (spec 019 A). */
+  orgs(): Promise<OrgsResponse> {
+    return this.request<OrgsResponse>("GET", "/api/v1/orgs");
+  }
+
+  /** Trades this token for one bound to another org. The server revokes the token used for the call. */
+  switchOrg(orgId: string): Promise<OrgSwitchResponse> {
+    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");
+    if (status < 200 || status >= 300) throw this.fail(status, json);
+  }
+
+  deviceCode(): Promise<DeviceCodeResponse> {
+    return this.request<DeviceCodeResponse>("POST", "/api/v1/device/code", { client_id: CLI_CLIENT_ID });
+  }
+
+  /** One poll. The four device errors come back as data (whatever status carries them); anything else throws. */
+  async deviceToken(deviceCode: string): Promise<DeviceTokenResponse> {
+    const { status, json } = await this.send("POST", "/api/v1/device/token", { device_code: deviceCode, client_id: CLI_CLIENT_ID });
+    const body = json as { error?: unknown; access_token?: unknown } | null;
+    if (body && typeof body.error === "string" && DEVICE_ERRORS.has(body.error)) return { error: body.error as DeviceTokenErrorCode };
+    if (status >= 200 && status < 300 && body && typeof body.access_token === "string") return json as DeviceTokenResponse;
+    if (status >= 200 && status < 300) throw new ApiFailure("The vfrey server sent an answer this version does not understand.", "update vfrey with `npx vfrey update`.", status);
+    throw this.fail(status, json);
+  }
+}

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();
+  }
+}