@vfrey/vfrey 0.0.1 → 1.0.0-beta.0

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

package/src/dashboard-link.ts

@@ -0,0 +1,180 @@
+import { mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import net from "node:net";
+import path from "node:path";
+import { canonicalPath } from "./project/canonical.js";
+import type { ResolvedHome } from "./home.js";
+
+export const DEFAULT_DASHBOARD_PORT = 4317;
+
+type Env = Record<string, string | undefined>;
+
+/** The port `npx vfrey dashboard` tries first without --port. VFREY_DASHBOARD_PORT moves it, for a machine where 4317 is busy. */
+export function defaultDashboardPort(env: Env): number {
+  const port = Number(env.VFREY_DASHBOARD_PORT);
+  return Number.isInteger(port) && port > 0 && port < 65536 ? port : DEFAULT_DASHBOARD_PORT;
+}
+
+/** Which desk a dashboard serves: its data folder, and the project when a project decided that folder. */
+export interface Desk {
+  dataDir: string;
+  project: { id: string; name: string } | null;
+}
+
+export function deskOf(home: Pick<ResolvedHome, "dataDir" | "project">): Desk {
+  return { dataDir: home.dataDir, project: home.project ? { id: home.project.id, name: home.project.name } : null };
+}
+
+/** What `.vfrey/dashboard.json` (or the machine desk's `dashboard.json`) holds. */
+export interface DashboardRecord {
+  port: number;
+  url: string;
+  pid: number;
+  projectId: string | null;
+  startedAt: string;
+}
+
+const recordFile = (dataDir: string) => path.join(dataDir, "dashboard.json");
+
+export function readDashboardRecord(dataDir: string): DashboardRecord | null {
+  try {
+    const raw = JSON.parse(readFileSync(recordFile(dataDir), "utf8")) as Partial<DashboardRecord>;
+    if (typeof raw.port !== "number" || !Number.isInteger(raw.port) || raw.port <= 0 || raw.port >= 65536) return null;
+    return {
+      port: raw.port,
+      url: typeof raw.url === "string" ? raw.url : `http://127.0.0.1:${raw.port}`,
+      pid: typeof raw.pid === "number" ? raw.pid : 0,
+      projectId: typeof raw.projectId === "string" ? raw.projectId : null,
+      startedAt: typeof raw.startedAt === "string" ? raw.startedAt : "",
+    };
+  } catch {
+    return null;
+  }
+}
+
+/** The dashboard notes itself in the data folder. The write is atomic, and the last dashboard to start owns the record. */
+export function writeDashboardRecord(dataDir: string, port: number, projectId: string | null = null, pid: number = process.pid): void {
+  try {
+    mkdirSync(dataDir, { recursive: true });
+    const record: DashboardRecord = { port, url: `http://127.0.0.1:${port}`, pid, projectId, startedAt: new Date().toISOString() };
+    const tmp = `${recordFile(dataDir)}.${pid}.tmp`;
+    writeFileSync(tmp, JSON.stringify(record) + "\n");
+    renameSync(tmp, recordFile(dataDir));
+  } catch {
+    /* the record is a convenience, never a reason to stop the dashboard */
+  }
+}
+
+/** Removes the record only while it still names this dashboard (pid and port). A newer dashboard's record is left alone. */
+export function removeDashboardRecord(dataDir: string, port?: number, pid: number = process.pid): void {
+  try {
+    const record = readDashboardRecord(dataDir);
+    if (!record || record.pid !== pid) return;
+    if (port !== undefined && record.port !== port) return;
+    rmSync(recordFile(dataDir), { force: true });
+  } catch {
+    /* no record, or not ours */
+  }
+}
+
+const canon = canonicalPath;
+
+/** Whether a GET /api/state body names this desk: the same data folder and the same project id (or both none). */
+export function stateMatchesDesk(state: unknown, desk: Desk): boolean {
+  if (!state || typeof state !== "object") return false;
+  const body = state as { ok?: unknown; dataDir?: unknown; project?: { id?: unknown } | null };
+  if (body.ok !== true || typeof body.dataDir !== "string") return false;
+  if (canon(body.dataDir) !== canon(desk.dataDir)) return false;
+  const served = body.project && typeof body.project.id === "string" ? body.project.id : null;
+  return served === (desk.project?.id ?? null);
+}
+
+/** Probes one origin. True only when it answers /api/state and says it serves this desk. */
+export async function servesDesk(origin: string, desk: Desk, timeoutMs = 300): Promise<boolean> {
+  try {
+    const response = await fetch(`${origin}/api/state`, { signal: AbortSignal.timeout(timeoutMs) });
+    if (!response.ok) return false;
+    return stateMatchesDesk(await response.json(), desk);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * The origin of a dashboard that is listening and serves this desk, or null. It tries the port the desk recorded,
+ * then the default one. A dashboard that serves another desk (another project, or the machine desk) does not count.
+ */
+export async function findDashboard(desk: Desk, env: Env = process.env, timeoutMs = 300): Promise<string | null> {
+  const ports = [...new Set([readDashboardRecord(desk.dataDir)?.port ?? null, defaultDashboardPort(env)].filter((port): port is number => port !== null))];
+  for (const port of ports) {
+    const origin = `http://127.0.0.1:${port}`;
+    if (await servesDesk(origin, desk, timeoutMs)) return origin;
+  }
+  return null;
+}
+
+/** Whether a TCP port on loopback can be bound right now. */
+export function canListen(port: number): Promise<boolean> {
+  return new Promise((resolve) => {
+    const server = net.createServer();
+    server.once("error", () => resolve(false));
+    server.listen(port, "127.0.0.1", () => server.close(() => resolve(true)));
+  });
+}
+
+/** The ports to try, in order: the one the desk recorded, then the default, then the ones above the default. */
+export function portCandidates(recorded: number | null, preferred: number, span = 50): number[] {
+  const list = [...(recorded !== null ? [recorded] : []), preferred];
+  for (let offset = 1; offset <= span && preferred + offset < 65536; offset += 1) list.push(preferred + offset);
+  return [...new Set(list)];
+}
+
+/** The first candidate that is free: the recorded port, else 4317 (VFREY_DASHBOARD_PORT), else the next free port up. */
+export async function pickPort(desk: Desk, env: Env, isFree: (port: number) => Promise<boolean> = canListen, skip: ReadonlySet<number> = new Set()): Promise<number> {
+  const candidates = portCandidates(readDashboardRecord(desk.dataDir)?.port ?? null, defaultDashboardPort(env));
+  for (const port of candidates) {
+    if (skip.has(port)) continue;
+    if (await isFree(port)) return port;
+  }
+  return 0;
+}
+
+const lockFile = (dataDir: string) => path.join(dataDir, "dashboard.lock");
+
+function alive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return (error as NodeJS.ErrnoException).code === "EPERM";
+  }
+}
+
+/**
+ * A short lock held while a dashboard picks its port and writes its record, so two starts at once (a tick and `open`)
+ * do not become two dashboards for one desk. Returns a release function, or null when another live start holds it.
+ */
+export function acquireStartLock(dataDir: string, staleMs = 20_000): (() => void) | null {
+  mkdirSync(dataDir, { recursive: true });
+  for (let attempt = 0; attempt < 2; attempt += 1) {
+    try {
+      writeFileSync(lockFile(dataDir), String(process.pid), { flag: "wx" });
+      return () => {
+        try {
+          if (readFileSync(lockFile(dataDir), "utf8") === String(process.pid)) rmSync(lockFile(dataDir), { force: true });
+        } catch {
+          /* already gone */
+        }
+      };
+    } catch {
+      try {
+        const holder = Number(readFileSync(lockFile(dataDir), "utf8"));
+        const age = Date.now() - statSync(lockFile(dataDir)).mtimeMs;
+        if (holder && alive(holder) && age < staleMs) return null;
+        rmSync(lockFile(dataDir), { force: true });
+      } catch {
+        /* the holder released it between the two reads: try again */
+      }
+    }
+  }
+  return null;
+}

package/src/dashboard-start.ts

@@ -0,0 +1,103 @@
+import { spawn } from "node:child_process";
+import { closeSync, mkdirSync, openSync, readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { findDashboard, type Desk } from "./dashboard-link.js";
+
+type Env = Record<string, string | undefined>;
+
+export type EnsureResult = { ok: true; origin: string; started: boolean } | { ok: false; message: string; fix: string };
+
+export interface EnsureOptions {
+  desk: Desk;
+  env: Env;
+  /** The folder the dashboard process starts in, so it finds the same project. Default is this process's folder. */
+  cwd?: string;
+  timeoutMs?: number;
+  /** Test hook: how to start the detached dashboard. Default spawns this CLI. */
+  spawnDashboard?: (logFile: string) => { pid?: number; exited: Promise<number | null> };
+}
+
+export const dashboardLogFile = (dataDir: string): string => path.join(dataDir, "dashboard.log");
+
+/** Starts `vfrey dashboard` as its own process: output to the log file, no stdin, and it outlives this process. */
+function spawnDetached(logFile: string, env: Env, cwd: string): { pid?: number; exited: Promise<number | null> } {
+  const here = path.dirname(fileURLToPath(import.meta.url));
+  const tsx = createRequire(import.meta.url).resolve("tsx");
+  mkdirSync(path.dirname(logFile), { recursive: true });
+  const fd = openSync(logFile, "a");
+  const child = spawn(
+    process.execPath,
+    ["--experimental-sqlite", "--disable-warning=ExperimentalWarning", "--import", tsx, path.join(here, "cli.ts"), "dashboard"],
+    { cwd, env: env as NodeJS.ProcessEnv, stdio: ["ignore", fd, fd], detached: true },
+  );
+  closeSync(fd);
+  const exited = new Promise<number | null>((resolve) => {
+    child.once("exit", (code) => resolve(code));
+    child.once("error", () => resolve(1));
+  });
+  child.unref();
+  return { pid: child.pid, exited };
+}
+
+function logTail(file: string): string {
+  try {
+    return readFileSync(file, "utf8").trim().split("\n").slice(-3).join(" | ");
+  } catch {
+    return "";
+  }
+}
+
+/**
+ * The one path to a live dashboard for a desk, used by `open` and by the tick summary: reuse the one that is listening,
+ * else start one detached and wait until /api/state answers and names this desk.
+ */
+export async function ensureDashboard(options: EnsureOptions): Promise<EnsureResult> {
+  const { desk, env } = options;
+  const existing = await findDashboard(desk, env);
+  if (existing) return { ok: true, origin: existing, started: false };
+  const logFile = dashboardLogFile(desk.dataDir);
+  let child;
+  try {
+    child = (options.spawnDashboard ?? ((file) => spawnDetached(file, env, options.cwd ?? process.cwd())))(logFile);
+  } catch (error) {
+    return { ok: false, message: `Could not start the dashboard: ${error instanceof Error ? error.message : String(error)}.`, fix: "run `npx vfrey doctor`, or start it by hand with `npx vfrey dashboard`." };
+  }
+  let exitCode: number | null | undefined;
+  void child.exited.then((code) => {
+    exitCode = code;
+  });
+  const deadline = Date.now() + (options.timeoutMs ?? 15_000);
+  while (Date.now() < deadline) {
+    await new Promise((resolve) => setTimeout(resolve, 150));
+    const origin = await findDashboard(desk, env);
+    if (origin) return { ok: true, origin, started: true };
+    // A child that exited without a dashboard having come up for this desk has failed; its log says why.
+    if (exitCode !== undefined) {
+      const origin = await findDashboard(desk, env, 1000);
+      if (origin) return { ok: true, origin, started: true };
+      const tail = logTail(logFile);
+      return { ok: false, message: `The dashboard exited at start (code ${exitCode})${tail ? `: ${tail}` : ""}.`, fix: `read ${logFile}, or run \`npx vfrey dashboard\` in the foreground to see the error.` };
+    }
+  }
+  const tail = logTail(logFile);
+  return { ok: false, message: `The dashboard did not answer within ${Math.round((options.timeoutMs ?? 15_000) / 1000)} s${tail ? `: ${tail}` : ""}.`, fix: `read ${logFile}, or run \`npx vfrey dashboard\` in the foreground to see the error.` };
+}
+
+/** Opens a URL in the default browser. Never throws; the URL is printed anyway. */
+export function openBrowser(url: string, platform: NodeJS.Platform = process.platform): void {
+  const [cmd, args]: [string, string[]] = platform === "darwin" ? ["open", [url]] : platform === "win32" ? ["cmd", ["/c", "start", "", url]] : ["xdg-open", [url]];
+  try {
+    const child = spawn(cmd, args, { stdio: "ignore", detached: true });
+    child.on("error", () => {});
+    child.unref();
+  } catch {
+    /* no browser: the printed URL is enough */
+  }
+}
+
+/** Whether to skip the browser: --no-browser, VFREY_NO_BROWSER=1, or a test runner. */
+export function browserDisabled(argv: string[], env: Env): boolean {
+  return argv.includes("--no-browser") || env.VFREY_NO_BROWSER === "1" || env.VITEST !== undefined || env.NODE_ENV === "test";
+}

package/src/desk/channel.ts

@@ -0,0 +1,64 @@
+import { credentialsKey, decryptSecret } from "@vfrey/contracts";
+import type { Store } from "../queue/store.js";
+
+export const CHANNEL_PLATFORMS = ["youtube", "tiktok", "instagram", "facebook"] as const;
+export type ChannelPlatform = (typeof CHANNEL_PLATFORMS)[number];
+
+/** Where each platform's channel or page id already lives. YouTube has none, so its id is stored in the platform config. */
+const ID_FIELD: Partial<Record<ChannelPlatform, string>> = {
+  tiktok: "tiktokOpenId",
+  instagram: "igUserId",
+  facebook: "fbPageId",
+};
+
+export interface ChannelInfo {
+  platform: ChannelPlatform;
+  enabled: boolean;
+  /** The id on file, or null when none is known yet. */
+  id: string | null;
+}
+
+/**
+ * The channel or page id each platform of a series is known by: the TikTok open id, the Instagram user id and the Facebook
+ * page id come from the series' stored keys, the YouTube channel id from the platform's `channelId` setting.
+ * These are public identifiers, not tokens. An id that cannot be decrypted counts as unknown.
+ */
+export function channelInfo(store: Store, seriesId: string, rawKey: string | undefined): ChannelInfo[] {
+  let key: Buffer | null = null;
+  try {
+    key = credentialsKey(rawKey ?? "");
+  } catch {
+    key = null;
+  }
+  const platforms = store.db.prepare(`SELECT platform, enabled, config_json FROM desk_platforms WHERE series_id = ?`).all(seriesId) as Array<{
+    platform: string;
+    enabled: number;
+    config_json: string;
+  }>;
+  return CHANNEL_PLATFORMS.map((platform) => {
+    const row = platforms.find((item) => item.platform === platform);
+    let id: string | null = null;
+    const field = ID_FIELD[platform];
+    if (field && key) {
+      const secret = store.db
+        .prepare(`SELECT ciphertext FROM desk_secrets WHERE owner_kind = 'series' AND owner_id = ? AND field = ?`)
+        .get(seriesId, field) as { ciphertext: string } | undefined;
+      if (secret) {
+        try {
+          id = decryptSecret(secret.ciphertext, key).trim() || null;
+        } catch {
+          id = null;
+        }
+      }
+    }
+    if (!id && row) {
+      try {
+        const config = JSON.parse(row.config_json) as { channelId?: unknown };
+        if (typeof config.channelId === "string" && config.channelId.trim()) id = config.channelId.trim();
+      } catch {
+        id = null;
+      }
+    }
+    return { platform, enabled: Boolean(row && Number(row.enabled) === 1), id };
+  });
+}