@vfrey/vfrey 0.0.1 → 1.0.0-beta.0

package/src/help.ts

@@ -0,0 +1,233 @@
+/** Help text. It prints and exits; it never opens the database or starts a job. */
+
+interface CommandHelp {
+  summary: string;
+  usage: string[];
+  flags: Array<[string, string]>;
+}
+
+export const HELP: Record<string, CommandHelp> = {
+  doctor: {
+    summary: "Check this machine (Node, home folder, Chrome, voice, skill). Exits 1 when a check fails.",
+    usage: ["npx vfrey doctor [--json] [--rules]"],
+    flags: [["--json", "print one JSON document; always exits 0, read .ok"], ["--rules", "also print the variation and compliance checklists"]],
+  },
+  login: {
+    summary: "Sign in to your vfrey account (paid features only; free ones never need it).",
+    usage: ["npx vfrey login [--api URL] [--no-browser]"],
+    flags: [["--api URL", "the vfrey server (default: VFREY_API_URL)"], ["--no-browser", "print the link only; also VFREY_NO_BROWSER=1"]],
+  },
+  logout: {
+    summary: "Sign out: revoke this machine's token on the server, then delete it here.",
+    usage: ["npx vfrey logout [--api URL]"],
+    flags: [["--api URL", "the vfrey server (default: VFREY_API_URL)"]],
+  },
+  whoami: {
+    summary: "Show your org, plan, entitlements and usage. VFREY_TOKEN signs in without login.",
+    usage: ["npx vfrey whoami [--json] [--api URL]"],
+    flags: [["--json", "print the server's answer as JSON"], ["--api URL", "the vfrey server (default: VFREY_API_URL)"]],
+  },
+  org: {
+    summary: "List your orgs, or switch the org this machine works in (accounts with several orgs).",
+    usage: ["npx vfrey org list [--json] [--api URL]", "npx vfrey org use ORG [--api URL]"],
+    flags: [["ORG", "an org name or id from `org list`"], ["--json", "list: print JSON"], ["--api URL", "the vfrey server (default: VFREY_API_URL)"]],
+  },
+  topics: {
+    summary: "What is trending in a niche, with evidence links (needs an account and credits; free features never do).",
+    usage: [
+      "npx vfrey topics --niche ID [--limit N] [--since ISO] [--json]",
+      "npx vfrey topics niches [--json]",
+      "npx vfrey topics request --name N --keywords a,b [--hashtags a,b] [--platforms tiktok,youtube]",
+    ],
+    flags: [
+      ["--niche ID", "the niche to read; list ids with `topics niches`"],
+      ["--limit N", "how many topics, 1 to 100 (default 20)"],
+      ["--since ISO", "only topics seen since this date"],
+      ["--json", "print the server's answer as JSON"],
+      ["niches", "list the niches; free, needs only the plan"],
+      ["request", "ask for a new niche from keywords; costs credits"],
+      ["--api URL", "the vfrey server (default: VFREY_API_URL)"],
+    ],
+  },
+  creators: {
+    summary: "Find creators in a niche and study their formats and hooks (needs the Research plan and credits; free features never do).",
+    usage: [
+      "npx vfrey creators search [--niche ID] [--platform tiktok,youtube] [--followers 10k-200k] [--posts-per-week 3] [--engagement 4%] [--sort engagement|growth|views|followers] [--limit N] [--json]",
+      "npx vfrey creators show @handle --platform tiktok [--json]",
+      "npx vfrey creators watch add|remove @handle --platform tiktok [--watchlist NAME]",
+      "npx vfrey creators watch list [--watchlist NAME] [--json]",
+      "npx vfrey creators export --watchlist ID > watchlist.csv",
+      "npx vfrey creators alerts [--json]",
+    ],
+    flags: [
+      ["--niche ID", "only creators in this niche; list ids with `topics niches`"],
+      ["--platform P", "tiktok, instagram or youtube; for search a comma list"],
+      ["--followers A-B", "a follower range: 10k-200k, 10k- (at least) or -200k (at most)"],
+      ["--posts-per-week N", "at least this many posts a week"],
+      ["--engagement 4%", "at least this engagement (4% or 0.04); it is a share of views or of followers, and the result says which"],
+      ["--sort KEY", "engagement, growth, views or followers (default engagement)"],
+      ["--limit N", "how many creators, 1 to 100 (default 20)"],
+      ["--watchlist NAME", "a watchlist by name or id (default for add and remove: Watching)"],
+      ["--json", "print the server's answer as JSON"],
+      ["export", "print one watchlist as CSV on stdout, at most 500 rows"],
+      ["alerts", "posts at 5x a watched creator's median views within 48 hours"],
+      ["--api URL", "the vfrey server (default: VFREY_API_URL)"],
+    ],
+  },
+  mail: {
+    summary: "Draft outreach (sponsor, brand, creator, client). A person approves and sends each draft (needs the Mail add-on).",
+    usage: [
+      "npx vfrey mail draft --kind sponsor|brand|creator_collab|client_update --need TEXT [--creator @handle --platform tiktok] [--to EMAIL] [--to-name N] [--tone T] [--json]",
+      "npx vfrey mail drafts [--status draft|approved|sent|failed|discarded] [--json]",
+      "npx vfrey mail show --id ID [--json]",
+      "npx vfrey mail approve --id ID",
+      "npx vfrey mail send --id ID",
+      "npx vfrey mail discard --id ID",
+      "npx vfrey mail identity [--from-name N --reply-to EMAIL --postal-address A --org NAME] [--json]",
+    ],
+    flags: [
+      ["--kind K", "sponsor, brand, creator_collab, client_update (or generic)"],
+      ["--need TEXT", "what the message should ask or say"],
+      ["--creator @h --platform P", "write to a creator from the index; --to defaults to their public business contact"],
+      ["draft", "writes a draft and prints it with its id; free, sends nothing"],
+      ["approve", "a person approves one draft; sends nothing. An agent token is refused"],
+      ["send", "a person sends one approved draft, once; charges one send. An agent token is refused"],
+      ["identity", "who mail is from, where replies go, and the postal address in every footer; a new reply-to must be confirmed by link before anything sends"],
+      ["--json", "print the server's answer as JSON"],
+      ["--api URL", "the vfrey server (default: VFREY_API_URL)"],
+    ],
+  },
+  tick: {
+    summary: "Run the pipeline once: source, generate, render, publish. Without --now it follows each series' cadence.",
+    usage: [
+      'npx vfrey tick --now [--about "<subject>"] [--script FILE] [--series <id>] [--engine <id>] [--dry-run] [--skip-render] [--json]',
+      "npx vfrey tick --script-template",
+    ],
+    flags: [
+      ["--now", "make a video now, ignoring the posting window"],
+      ["--about \"<subject>\"", "make the video about this subject; no feed is read (implies --now)"],
+      ["--script FILE", "use the script in this JSON file (title, hook, lines, hashtags) instead of a model; implies --now"],
+      ["--script-template", "print an example script JSON and exit"],
+      ["--scene DIR", "render the scene you wrote in DIR (index.html for vfrey-framey or hyperframes, index.tsx for remotion) instead of the default template"],
+      ["--series <id>", "only this series (desk tick)"],
+      ["--engine <id>", "render with remotion, vfrey-framey, or hyperframes for this run; beats the series, the project's vfrey.json engine and the machine default"],
+      ["--dry-run", "run every stage without a real render or upload"],
+      ["--skip-render", "skip the render; no real mp4"],
+      ["--json", "print one JSON document instead of the summary"],
+    ],
+  },
+  worker: {
+    summary: "Tick every 60 seconds until stopped (Ctrl-C).",
+    usage: ["npx vfrey worker [--dry-run]", "npx vfrey worker --all-projects [--once] [--dry-run]"],
+    flags: [["--dry-run", "no real render or upload"], ["--all-projects", "each cycle, tick every project in the machine index that has a due, unpaused series; logs to ~/.vfrey/logs/worker.log"], ["--once", "with --all-projects: run one cycle and exit"]],
+  },
+  service: {
+    summary: "Run the worker in the background on this machine (launchd on macOS, systemd --user on Linux).",
+    usage: ["npx vfrey service install", "npx vfrey service uninstall", "npx vfrey service status [--json]", "npx vfrey service logs [--follow]"],
+    flags: [["install", "write the launchd agent or systemd unit and start it; safe to run again"], ["uninstall", "stop it and remove the file"], ["status", "service state, last cycle, each project's last tick and next due time"], ["logs", "the last 50 lines of ~/.vfrey/logs/worker.log; --follow keeps printing"]],
+  },
+  engage: { summary: "Reply to comments on published videos for every series.", usage: ["npx vfrey engage [--dry-run]"], flags: [["--dry-run", "no real replies"]] },
+  analytics: { summary: "Collect view and like counts for published videos.", usage: ["npx vfrey analytics [--dry-run]"], flags: [["--dry-run", "no network reads"]] },
+  render: {
+    summary: "Render one vertical 1080x1920 short from a subject, without sourcing a job.",
+    usage: ['npx vfrey render --subject "<text>" [--engine <id>] [--composition <name>] [--output <file.mp4>]', "npx vfrey render --scene DIR --engine <id> [--script FILE] --frame <seconds> out.png"],
+    flags: [["--subject", "required; an empty subject is refused"], ["--engine", "remotion, vfrey-framey, or hyperframes; default is the project's vfrey.json engine, else the machine default (`engine list`)"], ["--composition", "default KineticType"], ["--output", "where to write the mp4"], ["--scene DIR", "render your scene instead; with --frame <seconds> OUT.png it writes one frame (silent, timing estimated from --script) so you can look at it"]],
+  },
+  scene: {
+    summary: "Write a starter scene: the HTML or React composition an agent edits to design a video.",
+    usage: ["npx vfrey scene init DIR [--engine framey|hyperframes|remotion]", "npx vfrey scene blocks [--category X]", "npx vfrey scene add BLOCK DIR", "npx vfrey scene transitions [--json]", "npx vfrey scene inspect DIR [--at SECONDS] [--selector CSS | --text \"words\"] [--script FILE] [--json]", "npx vfrey scene studio DIR [--port N] [--no-browser]"],
+    flags: [["inspect DIR", "before a \"change just this\" edit: which element, CSS rule and GSAP tween (with file:line) make the thing you name; --at seeks the timeline, --selector or --text narrows to it (default: every visible element); HTML scenes only"], ["studio DIR", "open an HTML scene in the visual editor (timeline, code, live preview) and save edits back into DIR; stays up until Ctrl+C. Binds 127.0.0.1 on a free port from 47000"], ["--port N", "studio only: use this port"], ["--no-browser", "studio only: print the address only (also VFREY_NO_BROWSER=1)"], ["init DIR", "write index.html (index.tsx for remotion) and vfrey's helper files into DIR"], ["blocks", "list the ready-made scene blocks; --category X narrows the list"], ["add BLOCK DIR", "copy a block into the scene in DIR and print the snippet to paste into #root"], ["transitions", "list the shader transitions for vfrey.transition() in HTML scenes (--json for machines)"], ["--engine", "framey (default), hyperframes, or remotion"]],
+  },
+  engine: {
+    summary: "List the render engines and choose the machine default.",
+    usage: ["npx vfrey engine list [--json]", "npx vfrey engine use <remotion|vfrey-framey|hyperframes>"],
+    flags: [["list", "each engine, ready or unavailable with the reason, and the current default"], ["use <engine>", "make this the default for every run that names no engine"]],
+  },
+  dashboard: {
+    summary: "Serve this desk's dashboard in the foreground (also: dev, desk serve). Prints `vfrey dashboard http://127.0.0.1:<port>` when ready; when this desk's dashboard is already listening it prints that address and exits 0.",
+    usage: ["npx vfrey dashboard [--port <n>]"],
+    flags: [["--port <n>", "force a port (0 picks any free one) and never reuse; without it: the recorded port if free, else 4317 (VFREY_DASHBOARD_PORT), else the next free port"]],
+  },
+  dev: { summary: "Same as dashboard.", usage: ["npx vfrey dev [--port <n>]"], flags: [["--port <n>", "default 4317"]] },
+  open: {
+    summary: "Open this project's dashboard: reuse it when it is listening, else start it detached, then print the URL. The one command to run when the person wants to look.",
+    usage: ["npx vfrey open [<run id | video path or title>] [--no-browser] [--json]"],
+    flags: [["<run id | video>", "open that run's page; a video is a path or title from `npx vfrey videos`"], ["--no-browser", "print the URL only (also VFREY_NO_BROWSER=1)"], ["--json", "print {url, started, project, runId}"]],
+  },
+  push: { summary: "Not built yet. Publishing runs inside tick once platform keys are set.", usage: ["npx vfrey push"], flags: [] },
+  update: { summary: "Print the commands that update the app and the skills.", usage: ["npx vfrey update [--apply]"], flags: [["--apply", "run them"]] },
+  desk: {
+    summary: "Read and change the desk database (accounts, series, jobs, secrets).",
+    usage: [
+      "npx vfrey desk snapshot --json",
+      "npx vfrey desk series create|update|pause|resume|delete --id <id> ... (update takes --engine <id>|default, --publish, --engage, --review true|false)",
+      "npx vfrey desk series live --id <id> --confirm <channel id> | --off   (a new series is dry-run until you go live)",
+      "npx vfrey desk job retry|cancel|delete --id <id>",
+      "npx vfrey desk job approve|reject --id <id> [--reason <text>]   (a job waits for review when its series has --review on; approve renders it on the next tick, reject ends it as rejected: review_rejected)",
+      "npx vfrey desk account create|rename|delete, secret set|clear, platform set|remove|disable, source add|update|remove, cadence set, mode set|clear",
+      "npx vfrey desk import --from <folder>",
+      "npx vfrey desk tick [--now] [--series <id>]",
+    ],
+    flags: [["--json", "snapshot prints JSON"]],
+  },
+  init: {
+    summary: "Make this folder a vfrey project: vfrey.json, package.json, AGENTS.md, CLAUDE.md, the skill for every agent, scenes/, scripts/, videos/ and a private .vfrey/ data folder. Run again to repair; existing files are kept. `npm create vfrey@latest my-channel` does this in a new folder and installs the package. In a folder with no project yet, run it as `npx @vfrey/vfrey init`.",
+    usage: ["npx vfrey init [--name <name>] [--engine <id>] [--from DIR]"],
+    flags: [
+      ["--name <name>", "the project name; default is the folder's name"],
+      ["--engine <id>", "record the project's preferred engine in vfrey.json (remotion, hyperframes, vfrey-framey, comfyui)"],
+      ["--from DIR", "import a data folder, such as the machine desk ~/.vfrey: its database (run ids kept), renders as videos/<date> <title>.mp4 with transcripts, and scene copies. The source is not changed and a busy source is refused. Running it again adds nothing."],
+    ],
+  },
+  videos: {
+    summary: "List finished videos, newest first: date, length, title, path. Works in a project or on the machine desk.",
+    usage: ["npx vfrey videos [--json] [--limit <n>]"],
+    flags: [["--json", "print one JSON document, with the project (or null)"], ["--limit <n>", "show only the newest n"]],
+  },
+  projects: {
+    summary: "List the projects on this machine, with each one's last video. A folder that is gone shows as missing.",
+    usage: ["npx vfrey projects [--json] [--prune]"],
+    flags: [["--json", "print one JSON document"], ["--prune", "drop projects whose folder is gone from the list"]],
+  },
+  skill: {
+    summary: "Install the vfrey skill where your coding agent finds it (Claude Code, Codex, Grok, Cursor, Gemini CLI).",
+    usage: [
+      "npx vfrey skill install [--agent claude|codex|grok|cursor|gemini|all] [--project] [--force]",
+      "npx vfrey skill install --dir <skills folder>",
+      "npx vfrey skill uninstall [--agent <agent>|--dir <folder>] [--project]",
+    ],
+    flags: [
+      ["--agent <name>", "which agent to install for (default claude): claude, codex, grok, cursor, gemini, or all"],
+      ["--project", "install into this folder's skills folder for that agent (for example ./.agents/skills for codex)"],
+      ["--dir <folder>", "any other agent: install into <folder>/vfrey"],
+      ["--force", "replace a different skill already named vfrey"],
+    ],
+  },
+};
+
+const ORDER = ["doctor", "tick", "worker", "service", "engage", "analytics", "render", "scene", "engine", "dashboard", "open", "push", "update", "desk", "skill", "init", "videos", "projects", "login", "logout", "whoami", "org", "topics", "creators", "mail"];
+
+export function generalHelp(): string {
+  const lines = ["vfrey: make short videos from your agent or the command line.", "", "Usage: npx vfrey <command> [flags]", "", "Commands:"];
+  for (const name of ORDER) lines.push(`  ${(name === "dashboard" ? "dashboard, dev" : name).padEnd(16)}${HELP[name]!.summary}`);
+  lines.push(
+    "",
+    "Common flags:",
+    "  tick --now --about \"<subject>\" --dry-run --json --series <id>",
+    "  open [run|video] --no-browser   dashboard --port <n>",
+    "  desk snapshot --json",
+    "  skill install --agent codex --project",
+    "  init --name my-channel   videos --limit 5   projects --prune",
+    "",
+    "Run `npx vfrey <command> --help` for one command's flags.",
+  );
+  return lines.join("\n") + "\n";
+}
+
+export function commandHelp(name: string): string | null {
+  const help = HELP[name];
+  if (!help) return null;
+  const lines = [help.summary, "", "Usage:", ...help.usage.map((line) => `  ${line}`)];
+  if (help.flags.length) lines.push("", "Flags:", ...help.flags.map(([flag, text]) => `  ${flag.padEnd(24)}${text}`));
+  return lines.join("\n") + "\n";
+}

package/src/home.ts

@@ -0,0 +1,45 @@
+import os from "node:os";
+import path from "node:path";
+import { findProject } from "./project/discover.js";
+import { canonicalPath } from "./project/canonical.js";
+import type { Project } from "./project/marker.js";
+
+type Env = Record<string, string | undefined>;
+
+/** Where the data folder came from, in precedence order. */
+export type DataSource = "DATA_DIR" | "VFREY_HOME" | "project" | "machine";
+
+export interface ResolvedHome {
+  dataDir: string;
+  source: DataSource;
+  /** The project that decided the data folder. Null when an env var or the machine desk did. */
+  project: Project | null;
+  /** The machine-wide folder: VFREY_HOME, else ~/.vfrey. It holds the project index. */
+  machineHome: string;
+}
+
+/** The machine-wide vfrey folder. The project index lives here; it is the data folder only outside a project. */
+export function vfreyHome(env: Env, homedir: string = os.homedir()): string {
+  if (env.VFREY_HOME) return path.resolve(env.VFREY_HOME);
+  // The background worker runs each project as a child with VFREY_HOME removed (so the project decides its data
+  // folder) and names the machine folder here, so the index and logs stay in one place.
+  if (env.VFREY_MACHINE_HOME) return path.resolve(env.VFREY_MACHINE_HOME);
+  return path.join(homedir, ".vfrey");
+}
+
+/**
+ * The one place the data folder is decided: DATA_DIR > VFREY_HOME > nearest project (`<root>/.vfrey`) > `~/.vfrey`.
+ * Every command goes through this (via dataDirFor / loadConfig), with the folder it was run in.
+ */
+export function resolveHome(env: Env, homedir: string = os.homedir(), cwd: string = process.cwd()): ResolvedHome {
+  const machineHome = vfreyHome(env, homedir);
+  if (env.DATA_DIR) return { dataDir: canonicalPath(env.DATA_DIR), source: "DATA_DIR", project: null, machineHome };
+  if (env.VFREY_HOME) return { dataDir: machineHome, source: "VFREY_HOME", project: null, machineHome };
+  const project = findProject(cwd);
+  if (project) return { dataDir: project.dataDir, source: "project", project, machineHome };
+  return { dataDir: machineHome, source: "machine", project: null, machineHome };
+}
+
+export function dataDirFor(env: Env, homedir: string = os.homedir(), cwd: string = process.cwd()): string {
+  return resolveHome(env, homedir, cwd).dataDir;
+}

package/src/llm/client.ts

@@ -0,0 +1,177 @@
+import { ConfigError, RetryableError } from "@vfrey/contracts";
+import { requestJson } from "@vfrey/contracts";
+import { cleanTitle, lowerFirst, standInTitle, subjectGist, subjectTag } from "../generate/title.js";
+
+export interface LlmRequest {
+  system: string;
+  user: string;
+  temperature: number;
+  maxTokens: number;
+}
+
+export interface LlmClient {
+  complete(input: LlmRequest): Promise<string>;
+}
+
+export function createLlmClient(input: {
+  provider: string;
+  baseUrl: string;
+  apiKey: string | null;
+  model: string;
+  fetchImpl?: typeof fetch;
+}): LlmClient {
+  const fetchImpl = input.fetchImpl ?? fetch;
+  if (input.provider === "mock" || input.provider === "none") return new MockLlm();
+  if (input.provider === "anthropic") {
+    return {
+      async complete(request) {
+        if (!input.apiKey) throw new ConfigError("llm_auth", "LLM_API_KEY is not set");
+        const result = await requestJson(fetchImpl, `${input.baseUrl}/v1/messages`, {
+          method: "POST",
+          headers: {
+            "content-type": "application/json",
+            "x-api-key": input.apiKey,
+            "anthropic-version": "2023-06-01",
+            ...(process.env.ANTHROPIC_WORKSPACE_ID
+              ? { "anthropic-workspace-id": process.env.ANTHROPIC_WORKSPACE_ID }
+              : {}),
+          },
+          body: JSON.stringify({
+            model: input.model,
+            max_tokens: request.maxTokens,
+            system: request.system,
+            messages: [{ role: "user", content: request.user }],
+          }),
+        });
+        if (result.status === 429 || result.status >= 500) {
+          throw new RetryableError("llm_rate", `Anthropic ${result.status}`);
+        }
+        refusedByProvider("Anthropic", result.status);
+        if (result.status >= 400) throw new RetryableError("llm_error", `Anthropic ${result.status}`);
+        const body = result.json as { content?: Array<{ type?: string; text?: string }> };
+        return (
+          body.content
+            ?.filter((part) => part.type === "text" || (part.type === undefined && part.text))
+            .map((part) => part.text ?? "")
+            .join("\n") ?? ""
+        );
+      },
+    };
+  }
+  return {
+    async complete(request) {
+      if (!input.apiKey) throw new ConfigError("llm_auth", "LLM_API_KEY is not set");
+      const result = await requestJson(fetchImpl, `${input.baseUrl}/chat/completions`, {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          authorization: `Bearer ${input.apiKey}`,
+        },
+        body: JSON.stringify({
+          model: input.model,
+          temperature: request.temperature,
+          max_tokens: request.maxTokens,
+          messages: [
+            { role: "system", content: request.system },
+            { role: "user", content: request.user },
+          ],
+        }),
+      });
+      if (result.status === 429 || result.status >= 500) {
+        throw new RetryableError("llm_rate", `${input.provider} ${result.status}`);
+      }
+      refusedByProvider(input.provider, result.status);
+      if (result.status >= 400) throw new RetryableError("llm_error", `${input.provider} ${result.status}`);
+      const body = result.json as { choices?: Array<{ message?: { content?: string } }> };
+      return body.choices?.[0]?.message?.content ?? "";
+    },
+  };
+}
+
+/** A key or model the provider refuses will refuse again. That is configuration, not a retry. */
+function refusedByProvider(provider: string, status: number): void {
+  if (status === 401 || status === 403) {
+    throw new ConfigError("llm_auth", `${provider} refused the LLM key (HTTP ${status}). Check LLM_API_KEY and its permissions.`);
+  }
+  if (status === 404) {
+    throw new ConfigError("llm_model", `${provider} did not find the model or endpoint (HTTP 404). Check LLM_MODEL and LLM_BASE_URL.`);
+  }
+}
+
+export function parseModelJson(text: string): unknown {
+  const fenced = text.match(/```(?:json)?\s*([\s\S]*?)```/);
+  const raw = (fenced?.[1] ?? text).trim();
+  return JSON.parse(raw) as unknown;
+}
+
+/** Deterministic stand-in so a dry run exercises every gate without a network model. */
+export class MockLlm implements LlmClient {
+  async complete(input: LlmRequest): Promise<string> {
+    if (input.user.includes("TASK:SCORE")) {
+      const risky = /diagnose|prescription|as your lawyer|investment advice/i.test(input.user);
+      return JSON.stringify({
+        score: risky ? 20 : 88,
+        safety: risky ? 4 : 24,
+        reason: risky ? "advice persona" : "specific and commentable",
+        riskClass: risky ? "compliance" : "ok",
+        complianceTags: risky ? ["financial_advice_persona"] : [],
+      });
+    }
+    if (input.user.includes("TASK:PACKAGE")) {
+      // An honest placeholder: the subject, cleaned, and lines that say so. It makes no claims about any topic.
+      const subject = cleanTitle(extractBetween(input.user, "SOURCE_TITLE:", "\n")) || "A short explainer";
+      const said = subject.replace(/[?!]+$/u, "");
+      // Inside a sentence the subject is lowercase-initial, and the spoken lines carry only the two words
+      // that bind them to it. The full subject lives in the title, so the lines never copy the source.
+      const mid = lowerFirst(said);
+      const gist = subjectGist(said);
+      const pattern = extractBetween(input.user, "HOOK_PATTERN:", "\n") || "question";
+      // The wording differs per hook pattern, so two placeholders in a row do not read as one hook.
+      const hooks: Record<string, string> = {
+        question: `Curious about ${gist}? Here is a quick look.`,
+        contrarian: `Take one minute for ${gist}.`,
+        story: `The short version of ${gist}, told fast.`,
+        statistic: `In under a minute: ${gist}.`,
+        "cold-open": `Start here: ${gist}.`,
+      };
+      const hook = hooks[pattern] ?? hooks.statistic!;
+      const tag = subjectTag(subject);
+      return JSON.stringify({
+        title: standInTitle(subject),
+        hook,
+        caption: `${hook} #explainer`,
+        description: `A placeholder script about ${mid}. Synthetic voice and graphics.`,
+        hashtags: ["#explainer", ...(tag ? [tag] : []), "#shorts"],
+        thumbnailPrompt: `Vertical poster, large words: ${said}`,
+        imagePrompts: [`Abstract diagram of ${mid}`, `Editorial still about ${mid}`],
+        beats: [
+          { role: "hook", text: hook, caption: hook, seconds: 3 },
+          { role: "setup", text: `This is a placeholder script. It makes no claims about ${gist}.`, caption: "A placeholder script", seconds: 4 },
+          { role: "turn", text: "Ask your agent to write the real one with --script.", caption: "Ask your agent", seconds: 4 },
+          { role: "payoff", text: "Until then, treat this video as a draft.", caption: "A draft", seconds: 4 },
+          { role: "cta", text: "Then make it again for the real thing.", caption: "Make it again", seconds: 3 },
+        ],
+      });
+    }
+    if (input.user.includes("TASK:REPLY")) {
+      const tone = extractBetween(input.user, "TONE:", "\n") || "genuine";
+      const comment = extractBetween(input.user, "COMMENT:", "\n") || "interesting";
+      if (tone === "spicy") {
+        return JSON.stringify({ tone, text: `Fair push on "${comment.slice(0, 40)}". The timing still holds.` });
+      }
+      if (tone === "oneliner") {
+        return JSON.stringify({ tone, text: "Glad that landed." });
+      }
+      return JSON.stringify({ tone, text: "The short version: the timing is the part that moves." });
+    }
+    return JSON.stringify({ ok: true });
+  }
+}
+
+function extractBetween(value: string, start: string, end: string): string {
+  const from = value.indexOf(start);
+  if (from < 0) return "";
+  const rest = value.slice(from + start.length);
+  const to = rest.indexOf(end);
+  return (to < 0 ? rest : rest.slice(0, to)).trim();
+}

package/src/log.ts

@@ -0,0 +1,7 @@
+// Structured log lines go to stderr. Stdout belongs to the command's own output, which agents parse.
+import { redact } from "@vfrey/contracts";
+
+export function log(level: string, message: string, fields: Record<string, unknown> = {}): void {
+  const line = redact(JSON.stringify({ ts: new Date().toISOString(), level, message, ...fields }));
+  process.stderr.write(line + "\n");
+}

package/src/oauth/tokens.ts

@@ -0,0 +1,189 @@
+import { ConfigError, RetryableError } from "@vfrey/contracts";
+import type { Account, AppConfig } from "@vfrey/contracts";
+import { requestJson } from "@vfrey/contracts";
+import { createHash } from "node:crypto";
+import { TokenVault, vaultKey } from "./vault.js";
+
+type Env = Record<string, string | undefined>;
+
+/** A Meta token is read from the environment again after this long, so a rotated token is picked up. */
+const META_TOKEN_DAYS = 50;
+
+function fingerprint(token: string): string {
+  return createHash("sha256").update(token).digest("hex").slice(0, 16);
+}
+
+function tokenEnvName(account: Account, platform: "youtube" | "tiktok" | "instagram" | "facebook"): string | null {
+  switch (platform) {
+    case "youtube":
+      return account.platforms.youtube?.refreshTokenEnv ?? null;
+    case "tiktok":
+      return account.platforms.tiktok?.refreshTokenEnv ?? null;
+    case "instagram":
+      return account.platforms.instagram?.accessTokenEnv ?? null;
+    default:
+      return account.platforms.facebook?.pageTokenEnv ?? null;
+  }
+}
+
+export async function accessToken(input: {
+  config: AppConfig;
+  account: Account;
+  platform: "youtube" | "tiktok" | "instagram" | "facebook";
+  env: Env;
+  vault: TokenVault;
+  fetchImpl: typeof fetch;
+  now: Date;
+}): Promise<string> {
+  const key = vaultKey(input.account.id, input.platform);
+  const envName = tokenEnvName(input.account, input.platform);
+  const envToken = envName ? input.env[envName] : undefined;
+  const seed = envToken ? fingerprint(envToken) : null;
+  let cached = input.vault.get(key);
+  // A token the operator set after the cache was seeded wins over the cache.
+  if (cached && seed && cached.seed && cached.seed !== seed) cached = null;
+  const context = { ...input, seed, envName };
+
+  if (input.platform === "instagram" || input.platform === "facebook") {
+    return metaToken(context, key, input.platform, cached);
+  }
+  if (cached?.accessToken && cached.accessExpiresAt) {
+    if (new Date(cached.accessExpiresAt).getTime() - input.now.getTime() > 5 * 60_000) {
+      return cached.accessToken;
+    }
+  }
+  if (input.platform === "youtube") return refreshGoogle(context, key, cached?.refreshToken ?? null);
+  return refreshTikTok(context, key, cached?.refreshToken ?? null);
+}
+
+function isInvalidGrant(json: unknown): boolean {
+  return Boolean(json) && typeof json === "object" && (json as { error?: unknown }).error === "invalid_grant";
+}
+
+async function refreshGoogle(
+  input: {
+    account: Account;
+    env: Env;
+    vault: TokenVault;
+    fetchImpl: typeof fetch;
+    now: Date;
+    seed: string | null;
+    envName: string | null;
+  },
+  key: string,
+  cachedRefresh: string | null,
+): Promise<string> {
+  const youtube = input.account.platforms.youtube;
+  if (!youtube) throw new ConfigError("oauth", "YouTube is not configured");
+  const refreshToken = cachedRefresh || required(input.env, youtube.refreshTokenEnv);
+  const body = new URLSearchParams({
+    client_id: required(input.env, youtube.clientIdEnv),
+    client_secret: required(input.env, youtube.clientSecretEnv),
+    refresh_token: refreshToken,
+    grant_type: "refresh_token",
+  });
+  const result = await requestJson(input.fetchImpl, "https://oauth2.googleapis.com/token", {
+    method: "POST",
+    headers: { "content-type": "application/x-www-form-urlencoded" },
+    body,
+  });
+  if (result.status === 400) {
+    if (isInvalidGrant(result.json)) {
+      input.vault.drop(key);
+      throw new ConfigError("oauth_refresh", `Google refused the refresh token (invalid_grant). Set ${youtube.refreshTokenEnv} to a new refresh token.`);
+    }
+    throw new ConfigError("oauth_refresh", "Google refused the token request (HTTP 400). Check the client id and secret.");
+  }
+  if (result.status >= 400) throw new RetryableError("oauth_refresh", `Google token HTTP ${result.status}`);
+  const json = result.json as { access_token?: string; expires_in?: number; refresh_token?: string };
+  if (!json.access_token) throw new RetryableError("oauth_refresh", "Google token response had no access_token");
+  const expires = new Date(input.now.getTime() + (json.expires_in ?? 3600) * 1000).toISOString();
+  input.vault.put(key, {
+    accessToken: json.access_token,
+    accessExpiresAt: expires,
+    refreshToken: json.refresh_token || refreshToken,
+    seed: input.seed ?? input.vault.get(key)?.seed ?? null,
+  });
+  return json.access_token;
+}
+
+async function refreshTikTok(
+  input: {
+    config?: AppConfig;
+    account: Account;
+    env: Env;
+    vault: TokenVault;
+    fetchImpl: typeof fetch;
+    now: Date;
+    configClient?: AppConfig;
+    seed: string | null;
+    envName: string | null;
+  } & { config: AppConfig },
+  key: string,
+  cachedRefresh: string | null,
+): Promise<string> {
+  const tiktok = input.account.platforms.tiktok;
+  if (!tiktok) throw new ConfigError("oauth", "TikTok is not configured");
+  if (!input.config.tiktok.clientKey || !input.config.tiktok.clientSecret) {
+    throw new ConfigError("oauth", "TIKTOK_CLIENT_KEY and TIKTOK_CLIENT_SECRET are required");
+  }
+  const refreshToken = cachedRefresh || required(input.env, tiktok.refreshTokenEnv);
+  const body = new URLSearchParams({
+    client_key: input.config.tiktok.clientKey,
+    client_secret: input.config.tiktok.clientSecret,
+    grant_type: "refresh_token",
+    refresh_token: refreshToken,
+  });
+  const result = await requestJson(input.fetchImpl, "https://open.tiktokapis.com/v2/oauth/token/", {
+    method: "POST",
+    headers: { "content-type": "application/x-www-form-urlencoded" },
+    body,
+  });
+  if (result.status === 400) {
+    if (isInvalidGrant(result.json)) {
+      input.vault.drop(key);
+      throw new ConfigError("oauth_refresh", `TikTok refused the refresh token (invalid_grant). Set ${tiktok.refreshTokenEnv} to a new refresh token.`);
+    }
+    throw new ConfigError("oauth_refresh", "TikTok refused the token request (HTTP 400). Check TIKTOK_CLIENT_KEY and TIKTOK_CLIENT_SECRET.");
+  }
+  if (result.status >= 400) throw new RetryableError("oauth_refresh", `TikTok token HTTP ${result.status}`);
+  const json = result.json as { access_token?: string; expires_in?: number; refresh_token?: string };
+  if (!json.access_token) throw new RetryableError("oauth_refresh", "TikTok token response had no access_token");
+  input.vault.put(key, {
+    accessToken: json.access_token,
+    accessExpiresAt: new Date(input.now.getTime() + (json.expires_in ?? 86400) * 1000).toISOString(),
+    refreshToken: json.refresh_token || refreshToken,
+    seed: input.seed ?? input.vault.get(key)?.seed ?? null,
+  });
+  return json.access_token;
+}
+
+function metaToken(
+  input: { account: Account; env: Env; vault: TokenVault; now: Date; seed: string | null },
+  key: string,
+  platform: "instagram" | "facebook",
+  cached: { accessToken: string | null; accessExpiresAt: string | null } | null,
+): string {
+  const envName =
+    platform === "instagram"
+      ? input.account.platforms.instagram?.accessTokenEnv
+      : input.account.platforms.facebook?.pageTokenEnv;
+  if (!envName) throw new ConfigError("oauth", `${platform} token env is not configured`);
+  const live =
+    cached?.accessToken && cached.accessExpiresAt && new Date(cached.accessExpiresAt).getTime() > input.now.getTime();
+  if (live) return cached.accessToken as string;
+  const token = input.env[envName];
+  // A cache from before tokens carried an expiry stands in only while the environment has no token.
+  if (!token && cached?.accessToken && !cached.accessExpiresAt) return cached.accessToken;
+  if (!token) throw new ConfigError("missing_env", `Environment variable ${envName} is not set`);
+  // The token is read from the environment again after META_TOKEN_DAYS, so a rotated token is picked up.
+  const expires = new Date(input.now.getTime() + META_TOKEN_DAYS * 86_400_000).toISOString();
+  input.vault.put(key, { accessToken: token, accessExpiresAt: expires, refreshToken: null, seed: input.seed });
+  return token;
+}
+
+function required(env: Env, name: string): string {
+  const value = env[name];
+  if (!value) throw new ConfigError("missing_env", `Environment variable ${name} is not set`);
+  return value;
+}