@vfrey/vfrey 0.0.1 → 1.0.0-beta.0

package/src/desk/verbs.ts

@@ -0,0 +1,361 @@
+import { existsSync, realpathSync } from "node:fs";
+import path from "node:path";
+import type { DeskResult, SeriesInput } from "../queue/desk-ops.js";
+import { CREDENTIALS_KEY_REFUSAL } from "../queue/desk-ops.js";
+import type { Store } from "../queue/store.js";
+import { engineById, engineStatus, otherReadyEngine, type EngineProbes } from "../product/engines.js";
+import { channelInfo } from "./channel.js";
+import { secretFieldError, type SecretOwnerKind } from "./secrets.js";
+
+export type VerbResult =
+  | { ok: true; data?: Record<string, unknown> }
+  | { ok: false; refusal: string; fix: string; code?: string };
+
+const PLATFORMS = ["youtube", "tiktok", "instagram", "facebook"];
+const SOURCE_KINDS = ["rss", "subreddit", "youtubeChannel", "youtubeTrending", "vfrey-topics"];
+/** A niche id from `npx vfrey topics niches`, such as ai-tools or my-niche-1a2b3c. */
+export const NICHE_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,79}$/;
+
+const good = (data?: Record<string, unknown>): VerbResult => (data ? { ok: true, data } : { ok: true });
+const no = (refusal: string, fix: string): VerbResult => ({ ok: false, refusal, fix });
+const urlRefusal = (value: string): VerbResult => ({
+  ok: false,
+  code: "source_url_rejected",
+  refusal: `source_url_rejected: "${value.slice(0, 80)}" is not an http or https URL.`,
+  fix: "Use a feed address that starts with http:// or https://.",
+});
+const isHttpUrl = (value: string): boolean => {
+  try {
+    const protocol = new URL(value).protocol;
+    return protocol === "http:" || protocol === "https:";
+  } catch {
+    return false;
+  }
+};
+const fromDesk = (result: DeskResult, fix: string, data?: Record<string, unknown>): VerbResult =>
+  result.ok ? good(data) : no(result.refusal, fix);
+
+const exists = (store: Store, table: "desk_accounts" | "desk_series", id: string): boolean =>
+  Boolean(store.db.prepare(`SELECT id FROM ${table} WHERE id = ?`).get(id));
+
+function nonNegative(values: Record<string, number>): VerbResult | null {
+  for (const [name, value] of Object.entries(values)) {
+    if (!Number.isFinite(value) || value < 0) return no(`${name} must be a number of zero or more.`, `Pass ${name} as a number such as 1.`);
+  }
+  return null;
+}
+
+export function snapshotRead(store: Store, input: { userId: string }): VerbResult {
+  return good(store.snapshot(input.userId));
+}
+
+export function accountCreate(store: Store, input: { id: string; name: string; ownerId?: string | null }): VerbResult {
+  if (exists(store, "desk_accounts", input.id)) return no(`Account ${input.id} already exists.`, "Pick another id, or rename the existing account.");
+  store.createAccount(input);
+  return good();
+}
+
+export function accountRename(store: Store, input: { id: string; name: string }): VerbResult {
+  return fromDesk(store.renameAccount(input.id, input.name), "Check the account id in `vfrey desk snapshot`.");
+}
+
+export function accountDelete(store: Store, input: { id: string }): VerbResult {
+  return fromDesk(store.deleteAccount(input.id), "Cancel or finish the account's open job, then delete it again.");
+}
+
+export function secretSet(
+  store: Store,
+  input: { ownerKind: SecretOwnerKind; ownerId: string; field: string; value: string; key: string | undefined },
+): VerbResult {
+  const bad = secretFieldError(input.ownerKind, input.field);
+  if (bad) return no(bad.refusal, bad.fix);
+  const saved = store.setSecret({
+    ownerKind: input.ownerKind,
+    ownerId: input.ownerId,
+    field: input.field,
+    plaintext: input.value,
+    key: input.key ?? "",
+  });
+  if ("ok" in saved) {
+    return saved.ok
+      ? good({ field: input.field, present: true })
+      : no(saved.refusal, saved.refusal === CREDENTIALS_KEY_REFUSAL ? "export CREDENTIALS_KEY=$(openssl rand -base64 32)" : "Check the value and try again.");
+  }
+  return good({ field: input.field, present: saved.present });
+}
+
+export function secretClear(store: Store, input: { ownerKind: SecretOwnerKind; ownerId: string; field: string }): VerbResult {
+  const bad = secretFieldError(input.ownerKind, input.field);
+  if (bad) return no(bad.refusal, bad.fix);
+  const cleared = store.clearSecret(input);
+  return good({ field: input.field, present: cleared.present });
+}
+
+/** Stores the machine default engine. A refusal names the reason and another ready engine. */
+export function engineUse(store: Store, input: { engine: string; probes: EngineProbes }): VerbResult {
+  let spec;
+  try {
+    spec = engineById(input.engine);
+  } catch {
+    return no(`${input.engine} is not an engine.`, "Run `npx vfrey engine list` to see the engines.");
+  }
+  const status = engineStatus(spec, input.probes);
+  if (status.availability === "unavailable") {
+    const other = otherReadyEngine(spec.id, input.probes);
+    return no(
+      `${spec.label} is unavailable: ${status.reason}.`,
+      other ? `Choose ${other.label}: \`npx vfrey engine use ${other.id}\`.` : "Run `npx vfrey doctor` to see what is missing.",
+    );
+  }
+  store.setEngineDefault(spec.id);
+  return good({ ok: true, engine: spec.id, label: spec.label });
+}
+
+export function seriesCreate(store: Store, input: SeriesInput): VerbResult {
+  if (!input.niche.trim()) return no("A series needs a niche.", "Pass --niche with one sentence about the topic.");
+  if (exists(store, "desk_series", input.id)) return no(`Series ${input.id} already exists.`, "Pick another id, or update the existing series.");
+  if (input.engine) {
+    const bad = engineProblem(input.engine);
+    if (bad) return bad;
+    input = { ...input, engine: input.engine === "default" ? "" : engineById(input.engine).id };
+  }
+  store.createSeries(input);
+  return good();
+}
+
+function engineProblem(value: string): VerbResult | null {
+  if (value === "" || value === "default") return null;
+  try {
+    engineById(value);
+    return null;
+  } catch {
+    return no(`${value} is not an engine.`, "Use remotion, hyperframes, vfrey-framey, comfyui, or default to follow the machine default.");
+  }
+}
+
+export function seriesUpdate(store: Store, input: { id: string; patch: Partial<SeriesInput> }): VerbResult {
+  if (input.patch.engine !== undefined) {
+    const bad = engineProblem(input.patch.engine);
+    if (bad) return bad;
+    if (input.patch.engine === "default") input.patch = { ...input.patch, engine: "" };
+    else if (input.patch.engine) input.patch = { ...input.patch, engine: engineById(input.patch.engine).id };
+  }
+  return fromDesk(store.updateSeries(input.id, input.patch), "Check the series id in `vfrey desk snapshot`.");
+}
+
+export function seriesDelete(store: Store, input: { id: string }): VerbResult {
+  return fromDesk(store.deleteSeries(input.id), "Cancel or finish the series' open job, then delete it again.");
+}
+
+/**
+ * Takes a series out of dry-run. The person types the channel or page id of one of its platforms. A mismatch refuses.
+ * When no id is on file for any enabled platform, the typed id is stored as the YouTube channel id (or the first enabled
+ * platform's) and the series goes live with it.
+ */
+export function seriesLive(store: Store, input: { id: string; confirm: string | undefined; key: string | undefined }): VerbResult {
+  if (!exists(store, "desk_series", input.id)) return no(`Series ${input.id} was not found.`, "Check the series id in `vfrey desk snapshot`.");
+  const typed = (input.confirm ?? "").trim();
+  const channels = channelInfo(store, input.id, input.key).filter((item) => item.enabled);
+  if (channels.length === 0) return no("No platform is on for this series, so there is nothing to go live on.", "Turn a platform on for the series first.");
+  if (!typed) {
+    return no("Going live needs the channel id typed once.", `Pass --confirm <channel id> with the id of the channel or page this series posts to (${channels.map((c) => c.platform).join(", ")}).`);
+  }
+  const known = channels.filter((item) => item.id !== null);
+  let matched: { platform: string; saved: boolean };
+  if (known.length > 0) {
+    const hit = known.find((item) => item.id === typed);
+    if (!hit) {
+      return no(
+        `That is not the channel id on file for ${input.id}.`,
+        "Copy the id shown for the account on the series page (or `desk snapshot`), then run `npx vfrey desk series live --id " + input.id + " --confirm <channel id>` again.",
+      );
+    }
+    matched = { platform: hit.platform, saved: false };
+  } else {
+    const target = channels[0]!;
+    const row = store.db.prepare(`SELECT config_json FROM desk_platforms WHERE series_id = ? AND platform = ?`).get(input.id, target.platform) as { config_json: string } | undefined;
+    let config: Record<string, unknown> = {};
+    try {
+      config = row ? (JSON.parse(row.config_json) as Record<string, unknown>) : {};
+    } catch {
+      config = {};
+    }
+    const saved = store.setPlatform({ seriesId: input.id, platform: target.platform, enabled: true, config: { ...config, channelId: typed } });
+    if (!saved.ok) return no(saved.refusal, "Check the id and try again.");
+    matched = { platform: target.platform, saved: true };
+  }
+  const result = store.setLive(
+    input.id,
+    true,
+    `Went live on ${matched.platform} (channel id ${typed}${matched.saved ? ", saved as the id on file" : ""}).`,
+  );
+  return fromDesk(result, "Check the series id in `vfrey desk snapshot`.", { id: input.id, live: true, platform: matched.platform, channelIdSaved: matched.saved });
+}
+
+/** Returns a series to dry-run. No confirm is needed. */
+export function seriesOff(store: Store, input: { id: string }): VerbResult {
+  return fromDesk(store.setLive(input.id, false, "Back to dry-run by the person."), "Check the series id in `vfrey desk snapshot`.", { id: input.id, live: false });
+}
+
+export function seriesPause(store: Store, input: { id: string }): VerbResult {
+  return fromDesk(store.pauseSeries(input.id), "Check the series id in `vfrey desk snapshot`.");
+}
+
+export function seriesResume(store: Store, input: { id: string }): VerbResult {
+  return fromDesk(store.resumeSeries(input.id), "Check the series id in `vfrey desk snapshot`.");
+}
+
+export function cadenceSet(
+  store: Store,
+  input: { seriesId: string; timezone: string; minHoursBetweenPosts: number; maxPostsPerDay: number; windows: string[] },
+): VerbResult {
+  const invalid = nonNegative({ minHoursBetweenPosts: input.minHoursBetweenPosts, maxPostsPerDay: input.maxPostsPerDay });
+  if (invalid) return invalid;
+  return fromDesk(
+    store.setCadence(input.seriesId, {
+      timezone: input.timezone,
+      minHoursBetweenPosts: input.minHoursBetweenPosts,
+      maxPostsPerDay: input.maxPostsPerDay,
+      windows: input.windows,
+    }),
+    "Check the series id in `vfrey desk snapshot`.",
+  );
+}
+
+export function cadenceClear(store: Store): VerbResult {
+  return fromDesk(store.clearCadence(), "Change the values with `vfrey desk cadence set`.");
+}
+
+export function quotaSet(
+  store: Store,
+  input: { seriesId: string; youtubeDailyUploadCap: number; maxRepliesPerDay: number; minSecondsBetween: number },
+): VerbResult {
+  const invalid = nonNegative({
+    youtubeDailyUploadCap: input.youtubeDailyUploadCap,
+    maxRepliesPerDay: input.maxRepliesPerDay,
+    minSecondsBetween: input.minSecondsBetween,
+  });
+  if (invalid) return invalid;
+  return fromDesk(
+    store.setQuota(input.seriesId, {
+      youtubeDailyUploadCap: input.youtubeDailyUploadCap,
+      maxRepliesPerDay: input.maxRepliesPerDay,
+      minSecondsBetween: input.minSecondsBetween,
+    }),
+    "Check the series id in `vfrey desk snapshot`.",
+  );
+}
+
+export function quotaClear(store: Store): VerbResult {
+  return fromDesk(store.clearQuota(), "Set the cap to 0 with `vfrey desk quota set`.");
+}
+
+export function platformSet(
+  store: Store,
+  input: { seriesId: string; platform: string; enabled: boolean; config?: Record<string, unknown> },
+): VerbResult {
+  if (!PLATFORMS.includes(input.platform)) return no(`${input.platform} is not a platform.`, `Use one of: ${PLATFORMS.join(", ")}.`);
+  return fromDesk(store.setPlatform(input), "Put credentials in `vfrey desk secret set`, not in platform config.");
+}
+
+export function platformDisable(store: Store, input: { seriesId: string; platform: string }): VerbResult {
+  return fromDesk(store.disablePlatform(input.seriesId, input.platform), "Check the series and platform in `vfrey desk snapshot`.");
+}
+
+export function platformRemove(store: Store, input: { seriesId: string; platform: string }): VerbResult {
+  return fromDesk(store.removePlatform(input.seriesId, input.platform), "Disable the platform with `vfrey desk platform disable`.");
+}
+
+export function sourceAdd(store: Store, input: { seriesId: string; kind: string; value: string }): VerbResult {
+  if (!SOURCE_KINDS.includes(input.kind)) return no(`${input.kind} is not a source kind.`, `Use one of: ${SOURCE_KINDS.join(", ")}.`);
+  if (!input.value.trim()) return no("A source needs a value.", "Pass --value with a feed URL, subreddit, channel id, or region.");
+  if (!exists(store, "desk_series", input.seriesId)) return no(`Series ${input.seriesId} was not found.`, "Check the series id in `vfrey desk snapshot`.");
+  if (input.kind === "rss" && !isHttpUrl(input.value.trim())) return urlRefusal(input.value.trim());
+  if (input.kind === "vfrey-topics" && !NICHE_ID.test(input.value.trim())) return no(`"${input.value.trim()}" is not a niche id.`, "Pass --value with an id from `npx vfrey topics niches`.");
+  return good({ ok: true, ...store.addSource({ ...input, value: input.value.trim() }) });
+}
+
+export function sourceUpdate(store: Store, input: { id: string; value: string }): VerbResult {
+  const row = store.db.prepare(`SELECT kind FROM desk_sources WHERE id = ?`).get(input.id) as { kind: string } | undefined;
+  if (row?.kind === "rss" && !isHttpUrl(input.value.trim())) return urlRefusal(input.value.trim());
+  return fromDesk(store.updateSource(input.id, input.value), "Check the source id in `vfrey desk snapshot`.");
+}
+
+export function sourceRemove(store: Store, input: { id: string }): VerbResult {
+  return fromDesk(store.removeSource(input.id), "Check the source id in `vfrey desk snapshot`.");
+}
+
+export function modeSet(store: Store, input: { userId: string; mode: string; llmKeyPresent: boolean }): VerbResult {
+  return fromDesk(
+    store.setMode(input.userId, input.mode, input.llmKeyPresent),
+    input.mode === "api" ? "export LLM_API_KEY=<key>, or use mode agent." : "Use `vfrey desk mode set agent` or `api`.",
+    { ok: true, mode: input.mode },
+  );
+}
+
+export function modeClear(store: Store, input: { userId: string }): VerbResult {
+  return fromDesk(store.clearMode(input.userId), "Run it again.");
+}
+
+export function jobRetry(store: Store, input: { id: string }): VerbResult {
+  return fromDesk(store.retryJob(input.id), "Cancel a leased job first, or check the id in `vfrey desk snapshot`.");
+}
+
+/** Releases a job that waits for review. The next tick renders it and the publish rules run as they always do. */
+export function jobApprove(store: Store, input: { id: string }): VerbResult {
+  return fromDesk(store.approveJob(input.id), "Only a job that waits for review can be approved. Check `npx vfrey desk snapshot --json` for awaiting_review jobs.", {
+    id: input.id,
+    status: "pending",
+    next: "The next tick renders it: npx vfrey tick (or let the worker do it).",
+  });
+}
+
+/** Ends a job that waits for review. It is `rejected` with the code `review_rejected` and never renders. */
+export function jobReject(store: Store, input: { id: string; reason?: string | null }): VerbResult {
+  return fromDesk(store.rejectJob(input.id, input.reason ?? null), "Only a job that waits for review can be rejected. Check `npx vfrey desk snapshot --json` for awaiting_review jobs.", {
+    id: input.id,
+    status: "rejected",
+    code: "review_rejected",
+  });
+}
+
+export function jobCancel(store: Store, input: { id: string }): VerbResult {
+  return fromDesk(store.cancelJob(input.id), "Wait for the job to start, or retry it instead.");
+}
+
+export function warningAck(store: Store, input: { id: string }): VerbResult {
+  return fromDesk(store.ackWarning(input.id), "Check the warning id in `vfrey desk snapshot`.");
+}
+
+export function warningDelete(store: Store): VerbResult {
+  return fromDesk(store.deleteWarning(), "Acknowledge it with `vfrey desk warning ack`.");
+}
+
+export function jobDelete(store: Store): VerbResult {
+  return fromDesk(store.deleteJob(), "Cancel a leased job with `vfrey desk job cancel`.");
+}
+
+export function publicationDelete(store: Store): VerbResult {
+  return fromDesk(store.deletePublication(), "Leave the row in place. It is the disclosure proof.");
+}
+
+export function metricDelete(store: Store): VerbResult {
+  return fromDesk(store.deleteMetric(), "Leave the snapshots in place. New readings add rows.");
+}
+
+export function commentDelete(store: Store): VerbResult {
+  return fromDesk(store.deleteComment(), "Leave the ledger in place. It stops a comment from being answered twice.");
+}
+
+export function deskImport(store: Store, input: { from: string }): VerbResult {
+  const from = path.resolve(input.from);
+  const file = path.join(from, "pipeline.sqlite");
+  if (!existsSync(file)) {
+    return no(`No pipeline.sqlite in ${from}.`, "Pass --from <folder> with the old data folder, such as ./data.");
+  }
+  if (store.dataDir && path.join(realpathSync(from), "pipeline.sqlite") === path.join(realpathSync(store.dataDir), "pipeline.sqlite")) {
+    return no("That folder holds the database already in use.", "Pass the old per-folder data directory, not the vfrey home.");
+  }
+  const result = store.importLegacy(from);
+  return good({ ok: true, imported: result.imported, files: result.files });
+}

package/src/doctor.ts

@@ -0,0 +1,212 @@
+import { accessSync, constants, existsSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { credentialsKey } from "@vfrey/contracts";
+import { resolveHome, type ResolvedHome } from "./home.js";
+import { installCommand } from "./skill-agents.js";
+import { findSkillCopies } from "./skill-install.js";
+import { cachedHeadlessShell, remotionCacheDir } from "./render/chrome.js";
+import { readMachineEngine } from "./product/engine-choice.js";
+import { allEngineStatuses, DEFAULT_ENGINE, engineById, engineStatus, statusText } from "./product/engines.js";
+import { probeEnginesSync } from "./product/probes.js";
+import { localVoiceProblem } from "./tts.js";
+import { accountLine } from "./api/commands.js";
+
+export { cachedHeadlessShell, remotionCacheDir };
+
+type Env = Record<string, string | undefined>;
+
+export interface DoctorCheck {
+  id: string;
+  ok: boolean;
+  label: string;
+  detail: string;
+  fix?: string;
+}
+
+export interface DoctorReport {
+  ok: boolean;
+  dataDir: string;
+  checks: DoctorCheck[];
+}
+
+const MIN_NODE = [22, 13];
+
+function nodeCheck(): DoctorCheck {
+  const [major = 0, minor = 0] = process.versions.node.split(".").map(Number);
+  const ok = major > MIN_NODE[0]! || (major === MIN_NODE[0] && minor >= MIN_NODE[1]!);
+  return {
+    id: "node",
+    ok,
+    label: "Node version",
+    detail: `Node ${process.versions.node}`,
+    ...(ok ? {} : { fix: `Install Node ${MIN_NODE.join(".")} or newer.` }),
+  };
+}
+
+/** The nearest folder that exists, so the check never creates the data folder. */
+function nearestExisting(dir: string): string {
+  let current = dir;
+  while (!existsSync(current)) {
+    const parent = path.dirname(current);
+    if (parent === current) break;
+    current = parent;
+  }
+  return current;
+}
+
+function homeCheck(dataDir: string): DoctorCheck {
+  const target = nearestExisting(dataDir);
+  try {
+    accessSync(target, constants.W_OK);
+    return { id: "home", ok: true, label: "Home directory", detail: `${dataDir} is writable` };
+  } catch {
+    return {
+      id: "home",
+      ok: false,
+      label: "Home directory",
+      detail: `${dataDir} is not writable`,
+      fix: "Set DATA_DIR or VFREY_HOME to a folder you can write to.",
+    };
+  }
+}
+
+function chromeCheck(env: Env, cwd: string): DoctorCheck {
+  const label = "Chrome for Remotion";
+  const cached = cachedHeadlessShell(cwd);
+  if (cached) return { id: "chrome", ok: true, label, detail: `Chrome Headless Shell is cached at ${cached}. The first render needs no download.` };
+  const candidates = [
+    env.BROWSER_EXECUTABLE,
+    "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+    "/Applications/Chromium.app/Contents/MacOS/Chromium",
+  ].filter((item): item is string => Boolean(item));
+  for (const dir of (env.PATH ?? "").split(path.delimiter)) {
+    for (const name of ["google-chrome", "google-chrome-stable", "chromium", "chromium-browser", "chrome"]) {
+      if (dir) candidates.push(path.join(dir, name));
+    }
+  }
+  const found = candidates.find((candidate) => existsSync(candidate));
+  if (found) {
+    return {
+      id: "chrome",
+      ok: true,
+      label,
+      detail: `System Chrome found at ${found}. Renders use Chrome Headless Shell, not this browser. The first render downloads Chrome Headless Shell (about 170 MB) unless it is already cached. Run \`npx remotion browser ensure\` to fetch it now.`,
+    };
+  }
+  return {
+    id: "chrome",
+    ok: false,
+    label,
+    detail: "No Chrome or Chrome Headless Shell was found",
+    fix: "Run `npx remotion browser ensure`, or install Chrome.",
+  };
+}
+
+function voiceCheck(env: Env): DoctorCheck {
+  const provider = env.TTS_PROVIDER === "openai" ? "openai" : env.TTS_PROVIDER === "none" ? "none" : "local";
+  if (provider === "none") return { id: "voice", ok: true, label: "Voice", detail: "TTS_PROVIDER=none, captions only" };
+  if (provider === "openai") {
+    const keyed = Boolean(env.TTS_API_KEY || env.LLM_API_KEY);
+    return keyed
+      ? { id: "voice", ok: true, label: "Voice", detail: "TTS_PROVIDER=openai with a key" }
+      : { id: "voice", ok: false, label: "Voice", detail: "TTS_PROVIDER=openai has no TTS_API_KEY", fix: "Set TTS_API_KEY, or set TTS_PROVIDER=none." };
+  }
+  const problem = localVoiceProblem(env);
+  if (problem) return { id: "voice", ok: false, label: "Voice", detail: problem.message, fix: problem.fix };
+  return { id: "voice", ok: true, label: "Voice", detail: "Local voice (say and ffmpeg) is available" };
+}
+
+function credentialsKeyCheck(env: Env): DoctorCheck {
+  const raw = env.CREDENTIALS_KEY;
+  if (!raw) return { id: "credentials_key", ok: true, label: "CREDENTIALS_KEY", detail: "Not set. Dashboard secrets stay off." };
+  try {
+    credentialsKey(raw);
+    return { id: "credentials_key", ok: true, label: "CREDENTIALS_KEY", detail: "Valid" };
+  } catch {
+    return {
+      id: "credentials_key",
+      ok: false,
+      label: "CREDENTIALS_KEY",
+      detail: "Not 32 bytes of base64",
+      fix: "Generate one with `openssl rand -base64 32`.",
+    };
+  }
+}
+
+/** Which data folder this run works on. Information only: it never fails. */
+function projectCheck(home: ResolvedHome): DoctorCheck {
+  const detail = home.project
+    ? `Project ${home.project.name} at ${home.project.root}`
+    : home.source === "machine"
+      ? "Not in a vfrey project; using the machine desk. Start one: npm create vfrey@latest my-channel"
+      : `Data folder set by ${home.source}`;
+  return { id: "project", ok: true, label: "Project", detail };
+}
+
+function skillCheck(env: Env, cwd: string, homedir: string): DoctorCheck {
+  const label = "Agent skill";
+  const copies = findSkillCopies(env, cwd, homedir);
+  const ours = copies.filter((copy) => copy.state !== "foreign");
+  const describe = (copy: (typeof copies)[number]) =>
+    `${copy.label} ${copy.kind} copy at ${copy.file} (${copy.state === "stale" ? (copy.was === "unversioned" ? "stale, unversioned" : `stale, version ${copy.was}`) : "up to date"})`;
+  if (ours.some((copy) => copy.state === "current")) {
+    return { id: "skill", ok: true, label, detail: `vfrey skill installed: ${ours.map(describe).join("; ")}` };
+  }
+  if (ours.length > 0) {
+    const fixes = [...new Set(ours.map((copy) => installCommand(copy.agent, copy.kind)))];
+    return {
+      id: "skill",
+      ok: false,
+      label,
+      detail: `The vfrey skill is older than this package: ${ours.map(describe).join("; ")}. The agent reads it first, so a stale copy will steer it to old commands.`,
+      fix: fixes.join("; "),
+    };
+  }
+  return {
+    id: "skill",
+    ok: false,
+    label,
+    detail: "The vfrey skill is not installed where Claude Code, Codex, Grok, Cursor or Gemini CLI look",
+    fix: "npx vfrey skill install --agent <your agent>  (claude, codex, grok, cursor, gemini, or all)",
+  };
+}
+
+/** Every engine's readiness, why an unavailable one is, and which is the default. */
+function enginesCheck(env: Env, cwd: string, dataDir: string): DoctorCheck {
+  const probes = probeEnginesSync(env, cwd);
+  let current = DEFAULT_ENGINE;
+  try {
+    current = engineById(readMachineEngine(dataDir) ?? DEFAULT_ENGINE).id;
+  } catch {
+    current = DEFAULT_ENGINE;
+  }
+  const rows = allEngineStatuses(probes);
+  const detail = `Default engine: ${current}. ${rows.map((row) => `${row.id} ${row.availability === "ready" ? statusText(row) : `unavailable (${row.reason})`}`).join("; ")}`;
+  const chosen = engineStatus(engineById(current), probes);
+  if (chosen.availability === "ready") return { id: "engines", ok: true, label: "Render engines", detail };
+  const other = rows.find((row) => row.availability === "ready");
+  return {
+    id: "engines",
+    ok: false,
+    label: "Render engines",
+    detail,
+    fix: `The default engine cannot render. Run \`npx vfrey engine use ${other?.id ?? "remotion"}\`.`,
+  };
+}
+
+export function runDoctor(env: Env, homedir: string = os.homedir(), cwd: string = process.cwd()): DoctorReport {
+  const home = resolveHome(env, homedir, cwd);
+  const dataDir = home.dataDir;
+  const checks = [nodeCheck(), projectCheck(home), homeCheck(dataDir), chromeCheck(env, cwd), enginesCheck(env, cwd, dataDir), voiceCheck(env), credentialsKeyCheck(env), skillCheck(env, cwd, homedir), { id: "account", ok: true, label: "Account", detail: accountLine(env, homedir) }];
+  return { ok: checks.every((check) => check.ok), dataDir, checks };
+}
+
+export function formatDoctor(report: DoctorReport): string {
+  const lines: string[] = [];
+  for (const check of report.checks) {
+    lines.push(`${check.ok ? "✓" : "✗"} ${check.id}: ${check.detail}`);
+    if (!check.ok && check.fix) lines.push(`  Fix: ${check.fix}`);
+  }
+  return lines.join("\n");
+}

package/src/drain.ts

@@ -0,0 +1,14 @@
+import { LEASE_MS, processJob, type Runtime } from "./pipeline/run.js";
+
+/** Runs queued jobs until none are due or the stop flag is set. Engage and analytics use it. */
+export async function drain(runtime: Runtime): Promise<number> {
+  let processed = 0;
+  for (;;) {
+    if (runtime.shouldStop?.()) break;
+    const job = runtime.store.claim(runtime.now(), runtime.leaseMs ?? LEASE_MS);
+    if (!job) break;
+    await processJob(runtime, job);
+    processed += 1;
+  }
+  return processed;
+}