@vfrey/vfrey 0.0.1 → 1.0.0-beta.1

package/src/cloud/job.ts

@@ -0,0 +1,106 @@
+import path from "node:path";
+
+/**
+ * The contract between whatever queues a render and the render worker (spec 019, section C).
+ *
+ * A job is a folder (`/job/in` in the container) holding `job.json`, the scene folder and, optionally, the voice track
+ * that was synthesised before the container started (the cloud image has no `say`). The worker writes `video.mp4`,
+ * `transcript.txt`, `checks.json` and `result.json` into another folder (`/job/out`).
+ */
+
+export const JOB_FILE = "job.json";
+export const JOB_VERSION = 1;
+export const JOB_ENGINES = ["vfrey-framey", "hyperframes", "remotion"] as const;
+export type JobEngine = (typeof JOB_ENGINES)[number];
+
+/** The most lines a job script may carry; the product's own limit for a script (src/generate/script.ts). */
+export const JOB_LIMITS = { titleMax: 200, linesMax: 40, lineMax: 400 } as const;
+
+export interface RenderJob {
+  version: 1;
+  engine: JobEngine;
+  /** The scene folder, relative to the input folder. `index.html` for the HTML engines, `index.tsx` for Remotion. */
+  scene: string;
+  script: { title: string; lines: string[] };
+  /** The voice track, relative to the input folder, already synthesised. Null renders a silent, estimated-timing video. */
+  voice: string | null;
+}
+
+export class JobError extends Error {
+  constructor(
+    message: string,
+    readonly code: string = "job_invalid",
+  ) {
+    super(message);
+    this.name = "JobError";
+  }
+}
+
+/**
+ * A path inside the input folder: relative, no `..`, no NUL. Returns the cleaned relative path.
+ * (Where the path resolves is checked again against the real folder at run time, so a symlink cannot lead out.)
+ */
+export function insidePath(value: unknown, field: string): string {
+  if (typeof value !== "string" || value.trim() === "") throw new JobError(`${field} must be a non-empty relative path.`);
+  if (value.includes("\0")) throw new JobError(`${field} must not contain a NUL byte.`);
+  if (path.isAbsolute(value) || /^[a-zA-Z]:/.test(value)) throw new JobError(`${field} must be relative to the input folder, not "${value}".`);
+  const clean = path.posix.normalize(value.split(path.sep).join("/"));
+  if (clean === ".." || clean.startsWith("../")) throw new JobError(`${field} must stay inside the input folder, not "${value}".`);
+  return clean === "." ? "." : clean;
+}
+
+/** Checks the parsed `job.json`. Throws a JobError naming the field; never returns a half-valid job. */
+export function parseJob(raw: unknown): RenderJob {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) throw new JobError("job.json must be a JSON object.");
+  const job = raw as Record<string, unknown>;
+  if (job.version !== JOB_VERSION) throw new JobError(`job.json version must be ${JOB_VERSION}, not ${JSON.stringify(job.version)}.`);
+  if (typeof job.engine !== "string" || !(JOB_ENGINES as readonly string[]).includes(job.engine)) {
+    throw new JobError(`engine must be one of ${JOB_ENGINES.join(", ")}, not ${JSON.stringify(job.engine)}.`);
+  }
+  const script = job.script as Record<string, unknown> | undefined;
+  if (!script || typeof script !== "object") throw new JobError("script must be an object with a title and lines.");
+  if (typeof script.title !== "string" || !script.title.trim() || script.title.length > JOB_LIMITS.titleMax) {
+    throw new JobError(`script.title must be 1 to ${JOB_LIMITS.titleMax} characters.`);
+  }
+  const lines = script.lines;
+  if (!Array.isArray(lines) || lines.length === 0 || lines.length > JOB_LIMITS.linesMax) {
+    throw new JobError(`script.lines must hold 1 to ${JOB_LIMITS.linesMax} lines.`);
+  }
+  for (const [i, line] of lines.entries()) {
+    if (typeof line !== "string" || !line.trim() || line.length > JOB_LIMITS.lineMax) throw new JobError(`script.lines[${i}] must be 1 to ${JOB_LIMITS.lineMax} characters.`);
+  }
+  const voice = job.voice === undefined || job.voice === null ? null : insidePath(job.voice, "voice");
+  return {
+    version: JOB_VERSION,
+    engine: job.engine as JobEngine,
+    scene: insidePath(job.scene, "scene"),
+    script: { title: script.title.trim(), lines: (lines as string[]).map((line) => line.trim()) },
+    voice,
+  };
+}
+
+export type JobStatus = "succeeded" | "rejected" | "failed" | "timeout";
+
+export interface CheckSummary {
+  id: string;
+  status: "pass" | "fail" | "skipped";
+  severity: string;
+  message: string;
+}
+
+/** `result.json`. The worker writes every field except `timeout`, which only the executor can know. */
+export interface RenderJobResult {
+  version: 1;
+  /** `succeeded`: the video exists and every check passed. `rejected`: it rendered but a check failed (do not publish). `failed`: no video. `timeout`: the executor killed it. */
+  status: JobStatus;
+  engine: JobEngine | null;
+  /** A stable code and a sentence for the person, set when the status is not `succeeded`. */
+  code: string | null;
+  message: string | null;
+  durations: { totalSec: number; renderSec: number | null; checksSec: number | null };
+  video: { width: number; height: number; durationSec: number; bytes: number } | null;
+  sizes: { videoBytes: number; transcriptBytes: number };
+  voice: "provided" | "none";
+  warnings: string[];
+  failedChecks: CheckSummary[];
+}

package/src/cloud/remote-job.ts

@@ -0,0 +1,67 @@
+import { mkdir, mkdtemp, readFile, rm, stat } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { unpackBundle } from "./bundle.js";
+import type { FetchLike } from "./gcs-sign.js";
+import type { RenderJobResult } from "./job.js";
+import { runRenderJob, type RenderJobIo } from "./render-job.js";
+
+type Env = Record<string, string | undefined>;
+
+/** The variables the cloud executor sets. They are removed from the environment the scene's render sees. */
+export const REMOTE_ENV = ["VFREY_JOB_IN_URL", "VFREY_JOB_OUT_URLS"] as const;
+const OUTPUT_NAMES = ["video.mp4", "transcript.txt", "checks.json", "result.json"] as const;
+
+/** A signed URL is only ever used if it points at Cloud Storage. */
+function storageUrl(value: unknown, field: string): string {
+  if (typeof value !== "string") throw new Error(`${field} is not set.`);
+  const url = new URL(value);
+  if (url.protocol !== "https:" || url.hostname !== "storage.googleapis.com") throw new Error(`${field} must be an https://storage.googleapis.com URL.`);
+  return url.toString();
+}
+
+/**
+ * `vfrey render-job --remote`: the Cloud Run Job's command (spec 019, section C2). It downloads the input bundle through
+ * a signed URL, renders with the same code as the local container, and uploads each output through its signed URL. It holds
+ * no credentials: the URLs are the only access, and they are removed from the environment before the render starts.
+ *
+ * Exit 0 when the outputs (above all `result.json`) were uploaded, even if the scene failed: the result file says so, and
+ * a non-zero exit would only make Cloud Run retry. Exit 1 when a download or an upload failed, which the executor reads
+ * as an infrastructure failure.
+ */
+export async function runRemoteJob(io: { env: Env; stdout: (t: string) => void; stderr: (t: string) => void; fetch?: FetchLike; workRoot?: string; render?: (io: RenderJobIo) => Promise<RenderJobResult> }): Promise<number> {
+  const fetchImpl = io.fetch ?? fetch;
+  const work = await mkdtemp(path.join(io.workRoot ?? os.tmpdir(), "vfrey-remote-"));
+  try {
+    const inUrl = storageUrl(io.env.VFREY_JOB_IN_URL, "VFREY_JOB_IN_URL");
+    const outUrls = JSON.parse(io.env.VFREY_JOB_OUT_URLS ?? "null") as Record<string, string> | null;
+    if (!outUrls) throw new Error("VFREY_JOB_OUT_URLS is not set.");
+    const targets = Object.fromEntries(OUTPUT_NAMES.map((name) => [name, storageUrl(outUrls[name], `VFREY_JOB_OUT_URLS.${name}`)]));
+
+    const response = await fetchImpl(inUrl);
+    if (!response.ok) throw new Error(`Downloading the input bundle failed with HTTP ${response.status}.`);
+    const inputDir = path.join(work, "in");
+    const outputDir = path.join(work, "out");
+    await mkdir(outputDir, { recursive: true });
+    await unpackBundle(Buffer.from(await response.arrayBuffer()), inputDir);
+
+    const env: Env = { ...io.env };
+    for (const name of REMOTE_ENV) delete env[name];
+    const result = await (io.render ?? runRenderJob)({ inputDir, outputDir, env, stderr: io.stderr });
+    io.stdout(`${JSON.stringify({ status: result.status, code: result.code, message: result.message })}\n`);
+
+    // result.json goes last: when it exists, every other output already does.
+    for (const name of [...OUTPUT_NAMES].sort((a) => (a === "result.json" ? 1 : -1))) {
+      const file = path.join(outputDir, name);
+      if (!(await stat(file).catch(() => null))) continue;
+      const put = await fetchImpl(targets[name]!, { method: "PUT", body: new Uint8Array(await readFile(file)) });
+      if (!put.ok) throw new Error(`Uploading ${name} failed with HTTP ${put.status}.`);
+    }
+    return 0;
+  } catch (error) {
+    io.stderr(`✗ render-job --remote: ${error instanceof Error ? error.message : String(error)}\n`);
+    return 1;
+  } finally {
+    await rm(work, { recursive: true, force: true });
+  }
+}

package/src/cloud/render-job.ts

@@ -0,0 +1,191 @@
+import { copyFile, mkdir, mkdtemp, readFile, realpath, rm, stat, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { linesToBeats } from "../generate/script.js";
+import { realTools, reviewRendered, wordTotal, type CheckResult } from "../pipeline/review.js";
+import { renderScene, type SceneEngine } from "../scene/render.js";
+import { checkScene, SceneError, storeScene } from "../scene/scene.js";
+import { JOB_FILE, JobError, parseJob, type CheckSummary, type RenderJob, type RenderJobResult } from "./job.js";
+
+type Env = Record<string, string | undefined>;
+
+export interface RenderJobIo {
+  /** The folder the job was mounted at. It is only read. */
+  inputDir: string;
+  /** The folder the outputs are written to. */
+  outputDir: string;
+  env?: Env;
+  stderr?: (text: string) => void;
+}
+
+const round1 = (n: number) => Math.round(n * 10) / 10;
+
+/** Resolves `rel` inside `root` and proves, with real paths, that it did not leave it (a symlink cannot lead out). */
+async function resolveInside(root: string, rel: string, field: string): Promise<string> {
+  const base = await realpath(root);
+  const target = await realpath(path.resolve(base, rel)).catch(() => {
+    throw new JobError(`${field} "${rel}" does not exist in the input folder.`, "job_missing_file");
+  });
+  if (target !== base && !target.startsWith(base + path.sep)) throw new JobError(`${field} "${rel}" resolves outside the input folder.`, "job_path_escape");
+  return target;
+}
+
+function summarize(checks: CheckResult[]): CheckSummary[] {
+  return checks.filter((c) => c.status === "fail").map((c) => ({ id: c.id, status: c.status, severity: c.severity, message: c.message }));
+}
+
+/**
+ * The worker's job: read `job.json`, render the scene with the product's own render path, run the after-render checks,
+ * and write the outputs. It makes no network request and reads no project or `~/.vfrey` state. A failure is reported in
+ * `result.json`; the returned result is what was written.
+ */
+export async function runRenderJob(io: RenderJobIo): Promise<RenderJobResult> {
+  const started = Date.now();
+  const env: Env = { ...(io.env ?? process.env) };
+  const log = io.stderr ?? (() => undefined);
+  const warnings: string[] = [];
+  const result: RenderJobResult = {
+    version: 1,
+    status: "failed",
+    engine: null,
+    code: null,
+    message: null,
+    durations: { totalSec: 0, renderSec: null, checksSec: null },
+    video: null,
+    sizes: { videoBytes: 0, transcriptBytes: 0 },
+    voice: "none",
+    warnings,
+    failedChecks: [],
+  };
+  const finish = async (): Promise<RenderJobResult> => {
+    result.durations.totalSec = round1((Date.now() - started) / 1000);
+    await mkdir(io.outputDir, { recursive: true });
+    await writeFile(path.join(io.outputDir, "result.json"), `${JSON.stringify(result, null, 2)}\n`);
+    return result;
+  };
+  const fail = (status: "failed", code: string, message: string) => {
+    result.status = status;
+    result.code = code;
+    result.message = message;
+  };
+  const work = await mkdtemp(path.join(os.tmpdir(), "vfrey-job-"));
+  try {
+    let job: RenderJob;
+    try {
+      job = parseJob(JSON.parse(await readFile(path.join(io.inputDir, JOB_FILE), "utf8")));
+    } catch (error) {
+      if (error instanceof JobError) fail("failed", error.code, error.message);
+      else fail("failed", "job_unreadable", `job.json could not be read: ${error instanceof Error ? error.message : String(error)}`);
+      return await finish();
+    }
+    result.engine = job.engine;
+    const transcript = `${job.script.lines.join("\n")}\n`;
+    await mkdir(io.outputDir, { recursive: true });
+    await writeFile(path.join(io.outputDir, "transcript.txt"), transcript);
+    result.sizes.transcriptBytes = Buffer.byteLength(transcript);
+
+    // A silent job: TTS_PROVIDER=none, or no voice in the job. The timing is then estimated from the script.
+    const silent = env.TTS_PROVIDER === "none" || job.voice === null;
+    let voicePath: string | null = null;
+    let sceneRoot: string;
+    try {
+      sceneRoot = await resolveInside(io.inputDir, job.scene, "scene");
+      if (!silent) voicePath = await resolveInside(io.inputDir, job.voice!, "voice");
+      if (voicePath && !(await stat(voicePath)).isFile()) throw new JobError("voice must be a file.", "job_missing_file");
+    } catch (error) {
+      if (error instanceof JobError) {
+        fail("failed", error.code, error.message);
+        return await finish();
+      }
+      throw error;
+    }
+    result.voice = voicePath ? "provided" : "none";
+
+    const rendered = path.join(work, "out", "video.mp4");
+    const renderStart = Date.now();
+    try {
+      // The scene is copied (and its SVGs sanitised, symlinks refused) before anything reads it.
+      await checkScene(sceneRoot, job.engine);
+      const stored = await storeScene(sceneRoot, path.join(work, "scene"));
+      warnings.push(...stored.warnings);
+      env.HOME = env.HOME || path.join(work, "home");
+      await renderScene({
+        engine: job.engine as SceneEngine,
+        sceneDir: path.join(work, "scene"),
+        title: job.script.title,
+        lines: job.script.lines,
+        beats: linesToBeats(job.script.lines).map((b) => ({ role: b.role, text: b.text, caption: b.caption })),
+        voiceoverPath: voicePath,
+        outputPath: rendered,
+        workDir: path.join(work, "render"),
+        env,
+        cwd: work,
+        warn: (message) => {
+          warnings.push(message);
+          log(`! ${message}\n`);
+        },
+      });
+    } catch (error) {
+      if (error instanceof SceneError) fail("failed", error.code, `${error.message} Fix: ${error.fix}`);
+      else fail("failed", "render_failed", `The render failed: ${error instanceof Error ? error.message : String(error)}`.slice(0, 600));
+      result.durations.renderSec = round1((Date.now() - renderStart) / 1000);
+      return await finish();
+    }
+    result.durations.renderSec = round1((Date.now() - renderStart) / 1000);
+
+    const checksStart = Date.now();
+    const checks = await reviewRendered({
+      file: rendered,
+      voicePath,
+      words: wordTotal(job.script.lines.join(" ")),
+      // The label is always burned by vfrey's render path for an agent-written scene.
+      labelBurned: true,
+      tools: realTools(env),
+    });
+    result.durations.checksSec = round1((Date.now() - checksStart) / 1000);
+    await writeFile(path.join(io.outputDir, "checks.json"), `${JSON.stringify(checks, null, 2)}\n`);
+    result.failedChecks = summarize(checks);
+
+    const dest = path.join(io.outputDir, "video.mp4");
+    await copyFile(rendered, dest);
+    const bytes = (await stat(dest)).size;
+    result.sizes.videoBytes = bytes;
+    const { probeVideo } = await import("../render/probe.js");
+    const probe = await probeVideo(dest, env);
+    result.video = probe ? { width: probe.width, height: probe.height, durationSec: probe.durationSec, bytes } : null;
+    if (result.failedChecks.length > 0) {
+      result.status = "rejected";
+      result.code = result.failedChecks[0]!.id;
+      result.message = `The finished video failed ${result.failedChecks.length} check${result.failedChecks.length === 1 ? "" : "s"}: ${result.failedChecks[0]!.message}`;
+    } else if (!probe) {
+      fail("failed", "video_unreadable", "The rendered file is not a readable video.");
+    } else {
+      result.status = "succeeded";
+    }
+    return await finish();
+  } finally {
+    await rm(work, { recursive: true, force: true });
+  }
+}
+
+/** `vfrey render-job --input DIR --output DIR`: the container's command. Exit 0 only for a succeeded job; the result file has the rest. */
+export async function runRenderJobCommand(argv: string[], io: { env: NodeJS.ProcessEnv; stdout: (t: string) => void; stderr: (t: string) => void }): Promise<number> {
+  if (argv.includes("--remote")) {
+    const { runRemoteJob } = await import("./remote-job.js");
+    return runRemoteJob(io);
+  }
+  const flag = (name: string) => {
+    const at = argv.indexOf(name);
+    const value = at === -1 ? undefined : argv[at + 1];
+    return value && !value.startsWith("--") ? value : null;
+  };
+  const input = flag("--input");
+  const output = flag("--output");
+  if (!input || !output) {
+    io.stderr("✗ render-job needs --input DIR and --output DIR.\nFix: run `vfrey render-job --input /job/in --output /job/out`.\n");
+    return 2;
+  }
+  const result = await runRenderJob({ inputDir: path.resolve(input), outputDir: path.resolve(output), env: io.env, stderr: io.stderr });
+  io.stdout(`${JSON.stringify({ status: result.status, code: result.code, message: result.message })}\n`);
+  return result.status === "succeeded" ? 0 : 1;
+}

package/src/config.ts

@@ -0,0 +1,309 @@
+import { existsSync, readFileSync } from "node:fs";
+import { ConfigError } from "@vfrey/contracts";
+import type { Account, AppConfig } from "@vfrey/contracts";
+import { dataDirFor } from "./home.js";
+
+type Env = Record<string, string | undefined>;
+
+function requiredString(value: unknown, path: string): string {
+  if (typeof value !== "string" || value.trim() === "") {
+    throw new ConfigError("account_config", `${path} must be a non-empty string`);
+  }
+  return value.trim();
+}
+
+function optionalString(value: unknown): string | null {
+  if (typeof value !== "string" || value.trim() === "") return null;
+  return value.trim();
+}
+
+function stringList(value: unknown, path: string): string[] {
+  if (value === undefined) return [];
+  if (!Array.isArray(value) || value.some((item) => typeof item !== "string")) {
+    throw new ConfigError("account_config", `${path} must be a string array`);
+  }
+  return value.map((item) => item.trim()).filter(Boolean);
+}
+
+function rejectInlineSecrets(value: unknown, path: string): void {
+  if (Array.isArray(value)) {
+    value.forEach((item, index) => rejectInlineSecrets(item, `${path}[${index}]`));
+    return;
+  }
+  if (!value || typeof value !== "object") return;
+  for (const [key, child] of Object.entries(value)) {
+    const childPath = `${path}.${key}`;
+    if (typeof child === "string") {
+      const secretKey = /token|secret|key/i.test(key);
+      const envName = key.endsWith("Env");
+      if (secretKey && !envName) {
+        throw new ConfigError(
+          "inline_secret",
+          `${childPath} looks like a credential field. Point it at an environment variable name ending in Env.`,
+        );
+      }
+      if (/^(ya29\.|act\.|sk-|xox[bap]-)/.test(child)) {
+        throw new ConfigError("inline_secret", `${childPath} contains a credential value. Store it in the environment.`);
+      }
+    } else {
+      rejectInlineSecrets(child, childPath);
+    }
+  }
+}
+
+export function parseAccounts(raw: unknown): Account[] {
+  rejectInlineSecrets(raw, "accounts");
+  const root = raw as { accounts?: unknown };
+  if (!root || !Array.isArray(root.accounts) || root.accounts.length === 0) {
+    throw new ConfigError("account_config", "accounts file must contain a non-empty accounts array");
+  }
+  return root.accounts.map((entry, index) => parseAccount(entry, index));
+}
+
+function parseAccount(entry: unknown, index: number): Account {
+  const path = `accounts[${index}]`;
+  const row = entry as Record<string, unknown>;
+  const cadence = (row.cadence ?? {}) as Record<string, unknown>;
+  const sources = (row.sources ?? {}) as Record<string, unknown>;
+  const platforms = (row.platforms ?? {}) as Record<string, unknown>;
+  const engage = (row.engage ?? {}) as Record<string, unknown>;
+  const voices = stringList(row.voices, `${path}.voices`);
+  if (voices.length === 0) {
+    throw new ConfigError("account_config", `${path}.voices needs at least one voice id`);
+  }
+  return {
+    id: requiredString(row.id, `${path}.id`),
+    niche: requiredString(row.niche, `${path}.niche`),
+    language: optionalString(row.language) ?? "en",
+    cadence: {
+      timezone: requiredString(cadence.timezone, `${path}.cadence.timezone`),
+      minHoursBetweenPosts: numberOr(cadence.minHoursBetweenPosts, 18),
+      maxPostsPerDay: numberOr(cadence.maxPostsPerDay, 1),
+      windows: stringList(cadence.windows, `${path}.cadence.windows`),
+    },
+    voices,
+    hashtagPool: stringList(row.hashtagPool, `${path}.hashtagPool`),
+    sources: {
+      rss: stringList(sources.rss, `${path}.sources.rss`),
+      subreddits: stringList(sources.subreddits, `${path}.sources.subreddits`),
+      youtubeChannelIds: stringList(sources.youtubeChannelIds, `${path}.sources.youtubeChannelIds`),
+      youtubeTrendingRegion: optionalString(sources.youtubeTrendingRegion),
+    },
+    platforms: {
+      youtube: platforms.youtube ? parseYouTube(platforms.youtube, `${path}.platforms.youtube`) : undefined,
+      tiktok: platforms.tiktok ? parseTikTok(platforms.tiktok, `${path}.platforms.tiktok`) : undefined,
+      instagram: platforms.instagram ? parseInstagram(platforms.instagram, `${path}.platforms.instagram`) : undefined,
+      facebook: platforms.facebook ? parseFacebook(platforms.facebook, `${path}.platforms.facebook`) : undefined,
+    },
+    engage: {
+      enabled: engage.enabled !== false,
+      allowSpicy: engage.allowSpicy === true,
+      maxRepliesPerDay: numberOr(engage.maxRepliesPerDay, 20),
+      minSecondsBetweenReplies: numberOr(engage.minSecondsBetweenReplies, 45),
+    },
+    waiveAudioRotation: row.waiveAudioRotation === true,
+  };
+}
+
+function parseYouTube(value: unknown, path: string): Account["platforms"]["youtube"] {
+  const row = value as Record<string, unknown>;
+  const privacy = optionalString(row.privacyStatus) ?? "private";
+  if (privacy !== "public" && privacy !== "private" && privacy !== "unlisted") {
+    throw new ConfigError("account_config", `${path}.privacyStatus is invalid`);
+  }
+  return {
+    enabled: row.enabled !== false,
+    privacyStatus: privacy,
+    categoryId: optionalString(row.categoryId) ?? "22",
+    madeForKids: row.madeForKids === true,
+    refreshTokenEnv: requiredString(row.refreshTokenEnv, `${path}.refreshTokenEnv`),
+    clientIdEnv: requiredString(row.clientIdEnv, `${path}.clientIdEnv`),
+    clientSecretEnv: requiredString(row.clientSecretEnv, `${path}.clientSecretEnv`),
+    notifySubscribers: typeof row.notifySubscribers === "boolean" ? row.notifySubscribers : null,
+  };
+}
+
+function parseTikTok(value: unknown, path: string): Account["platforms"]["tiktok"] {
+  const row = value as Record<string, unknown>;
+  const privacy = optionalString(row.privacyLevel) ?? "SELF_ONLY";
+  const allowed = ["PUBLIC_TO_EVERYONE", "MUTUAL_FOLLOW_FRIENDS", "FOLLOWER_OF_CREATOR", "SELF_ONLY"];
+  if (!allowed.includes(privacy)) throw new ConfigError("account_config", `${path}.privacyLevel is invalid`);
+  return {
+    enabled: row.enabled !== false,
+    privacyLevel: privacy as "SELF_ONLY",
+    refreshTokenEnv: requiredString(row.refreshTokenEnv, `${path}.refreshTokenEnv`),
+    openIdEnv: requiredString(row.openIdEnv, `${path}.openIdEnv`),
+    brandContent: row.brandContent === true,
+    brandOrganic: row.brandOrganic === true,
+    disableComment: row.disableComment === true,
+  };
+}
+
+function parseInstagram(value: unknown, path: string): Account["platforms"]["instagram"] {
+  const row = value as Record<string, unknown>;
+  return {
+    enabled: row.enabled !== false,
+    igUserIdEnv: requiredString(row.igUserIdEnv, `${path}.igUserIdEnv`),
+    accessTokenEnv: requiredString(row.accessTokenEnv, `${path}.accessTokenEnv`),
+    shareToFeed: row.shareToFeed !== false,
+  };
+}
+
+function parseFacebook(value: unknown, path: string): Account["platforms"]["facebook"] {
+  const row = value as Record<string, unknown>;
+  return {
+    enabled: row.enabled !== false,
+    pageIdEnv: requiredString(row.pageIdEnv, `${path}.pageIdEnv`),
+    pageTokenEnv: requiredString(row.pageTokenEnv, `${path}.pageTokenEnv`),
+  };
+}
+
+function numberOr(value: unknown, fallback: number): number {
+  if (typeof value !== "number" || !Number.isFinite(value)) return fallback;
+  return value;
+}
+
+export function loadConfig(env: Env, accountsJson?: string): AppConfig {
+  const accountsFile = env.ACCOUNTS_FILE || "accounts.json";
+  const raw = accountsJson ?? (existsSync(accountsFile) ? readFileSync(accountsFile, "utf8") : null);
+  const accounts = raw === null ? [] : parseAccounts(JSON.parse(raw) as unknown);
+  const provider = env.LLM_PROVIDER || "mock";
+  return {
+    appEnv: env.APP_ENV === "production" ? "production" : "qa",
+    dataDir: dataDirFor(env),
+    accountsFile,
+    dryRun: env.PIPELINE_DRY_RUN === "true",
+    llm: {
+      provider,
+      baseUrl: env.LLM_BASE_URL || defaultLlmBase(provider),
+      apiKey: env.LLM_API_KEY || null,
+      model: env.LLM_MODEL || defaultLlmModel(provider),
+    },
+    tts: {
+      provider: env.TTS_PROVIDER === "openai" ? "openai" : env.TTS_PROVIDER === "none" ? "none" : "local",
+      baseUrl: env.TTS_BASE_URL || "https://api.openai.com/v1",
+      apiKey: env.TTS_API_KEY || env.LLM_API_KEY || null,
+      model: env.TTS_MODEL || "tts-1",
+    } as AppConfig["tts"],
+    googleApiKey: env.YOUTUBE_API_KEY || null,
+    reddit: {
+      clientId: env.REDDIT_CLIENT_ID || null,
+      clientSecret: env.REDDIT_CLIENT_SECRET || null,
+      userAgent: env.REDDIT_USER_AGENT || "vfrey:v1 (by /u/operator)",
+    },
+    tiktok: {
+      clientKey: env.TIKTOK_CLIENT_KEY || null,
+      clientSecret: env.TIKTOK_CLIENT_SECRET || null,
+      clientAudited: env.TIKTOK_CLIENT_AUDITED === "true",
+    },
+    meta: {
+      graphVersion: env.META_GRAPH_VERSION || "v26.0",
+      appId: env.META_APP_ID || null,
+      appSecret: env.META_APP_SECRET || null,
+    },
+    youtube: {
+      dailyUploadCap: Number(env.YOUTUBE_DAILY_UPLOAD_CAP || "90"),
+    },
+    accounts,
+  };
+}
+
+function defaultLlmBase(provider: string): string {
+  switch (provider) {
+    case "openai":
+      return "https://api.openai.com/v1";
+    case "groq":
+      return "https://api.groq.com/openai/v1";
+    case "xai":
+      return "https://api.x.ai/v1";
+    case "gemini":
+      return "https://generativelanguage.googleapis.com/v1beta/openai";
+    case "anthropic":
+      return "https://api.anthropic.com";
+    default:
+      return "";
+  }
+}
+
+function defaultLlmModel(provider: string): string {
+  switch (provider) {
+    case "anthropic":
+      return "claude-sonnet-5-5";
+    case "gemini":
+      return "gemini-2.5-flash";
+    case "groq":
+      return "llama-3.3-70b-versatile";
+    case "xai":
+      return "grok-4";
+    case "openai":
+      return "gpt-4.1-mini";
+    default:
+      return "mock";
+  }
+}
+
+export function envValue(env: Env, name: string): string {
+  const value = env[name];
+  if (!value) throw new ConfigError("missing_env", `Environment variable ${name} is not set`);
+  return value;
+}
+
+export interface Refusal {
+  message: string;
+  fix: string;
+}
+
+function platformEnvNames(account: Account): string[] {
+  const names: string[] = [];
+  const p = account.platforms;
+  if (p.youtube?.enabled) names.push(p.youtube.refreshTokenEnv, p.youtube.clientIdEnv, p.youtube.clientSecretEnv);
+  if (p.tiktok?.enabled) names.push(p.tiktok.refreshTokenEnv, p.tiktok.openIdEnv);
+  if (p.instagram?.enabled) names.push(p.instagram.igUserIdEnv, p.instagram.accessTokenEnv);
+  if (p.facebook?.enabled) names.push(p.facebook.pageIdEnv, p.facebook.pageTokenEnv);
+  return names;
+}
+
+/**
+ * The mock writer produces canned copy. Outside a dry run it must never feed a platform
+ * the operator has keys for. Returns the refusal, or null when the run may go on.
+ */
+export function mockWriterRefusal(config: AppConfig, env: Env, dryRun: boolean): Refusal | null {
+  if (dryRun) return null;
+  if (config.llm.provider !== "mock" && config.llm.provider !== "none") return null;
+  const keyed = config.accounts.some((account) => platformEnvNames(account).some((name) => Boolean(env[name])));
+  if (!keyed) return null;
+  return {
+    message: "LLM_PROVIDER is mock and a platform key is set. The mock writer would publish canned copy.",
+    fix: "Set LLM_PROVIDER and LLM_API_KEY to a real model, or run with --dry-run.",
+  };
+}
+
+const WINDOW = /^(\d{2}):(\d{2})-(\d{2}):(\d{2})$/;
+
+/** Returns a sentence naming the first fault in a cadence, or null when it is usable. */
+export function validateCadence(cadence: {
+  timezone: string;
+  minHoursBetweenPosts: number;
+  maxPostsPerDay: number;
+  windows: string[];
+}): string | null {
+  try {
+    new Intl.DateTimeFormat("en-US", { timeZone: cadence.timezone });
+  } catch {
+    return `timezone ${JSON.stringify(cadence.timezone)} is not a valid IANA timezone`;
+  }
+  if (!Number.isFinite(cadence.minHoursBetweenPosts) || cadence.minHoursBetweenPosts < 0) {
+    return "minHoursBetweenPosts must be a number of hours, 0 or more";
+  }
+  if (!Number.isFinite(cadence.maxPostsPerDay) || cadence.maxPostsPerDay < 0) {
+    return "maxPostsPerDay must be a number, 0 or more";
+  }
+  for (const window of cadence.windows) {
+    const match = WINDOW.exec(window);
+    const ok =
+      match !== null &&
+      Number(match[1]) < 24 && Number(match[3]) < 24 && Number(match[2]) < 60 && Number(match[4]) < 60;
+    if (!ok) return `window ${JSON.stringify(window)} must look like 09:00-17:30`;
+  }
+  return null;
+}