@vfrey/vfrey 0.0.1 → 1.0.0-beta.0

package/src/scene/transitions.ts

@@ -0,0 +1,26 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { TRANSITION_TYPES, DEFAULT_TRANSITION, DEFAULT_TRANSITION_SECONDS, type TransitionType } from "./runtime/transitions.js";
+import { TRANSITIONS_DIR } from "./supply.js";
+
+export interface TransitionIndex {
+  source: string;
+  commit: string;
+  runtime: { file: string; bytes: number };
+  default: string;
+  defaultSeconds: number;
+  transitions: TransitionType[];
+}
+
+/** The transition types a scene can use, with where the runtime came from (src/scene/transitions/SOURCE.json). */
+export async function transitionIndex(): Promise<TransitionIndex> {
+  const source = JSON.parse(await readFile(path.join(TRANSITIONS_DIR, "SOURCE.json"), "utf8")) as { source: string; commit: string; bytes: number; shaders: string[] };
+  const known = new Set(TRANSITION_TYPES.map((t) => t.name));
+  const shipped = new Set(source.shaders);
+  for (const name of source.shaders) if (!known.has(name)) throw new Error(`the transitions runtime has a shader, ${name}, that vfrey does not describe.`);
+  for (const t of TRANSITION_TYPES) if (t.gpu && !shipped.has(t.name)) throw new Error(`vfrey lists the transition ${t.name}, which the runtime does not have.`);
+  return { source: source.source, commit: source.commit, runtime: { file: "vfrey/transitions.js", bytes: source.bytes }, default: DEFAULT_TRANSITION, defaultSeconds: DEFAULT_TRANSITION_SECONDS, transitions: [...TRANSITION_TYPES] };
+}
+
+/** The text a Remotion scene gets when it asks for a shader transition. */
+export const REMOTION_TRANSITIONS_FIX = "use an HTML scene (`npx vfrey scene init DIR`) with --engine vfrey-framey or hyperframes, or build the transition in React with Remotion's own interpolate().";

package/src/service/all-projects.ts

@@ -0,0 +1,153 @@
+import { spawn } from "node:child_process";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { isMissing, readIndex, type IndexEntry } from "../project/index-file.js";
+import { projectQueue, projectSeriesDue, type ProjectQueue, type SeriesDue } from "./due.js";
+import type { FileLog } from "./log-file.js";
+import { LOCK_BUSY_EXIT, liveHolder } from "./lock.js";
+import { readState, writeState } from "./state.js";
+
+export type Outcome = "ticked" | "not due" | "busy" | "missing" | "no series" | "error";
+
+export interface ProjectResult {
+  id: string;
+  name: string;
+  root: string;
+  outcome: Outcome;
+  detail?: string;
+  /** Jobs waiting for review in the project. */
+  waiting?: number;
+}
+
+export interface CycleReport {
+  at: string;
+  projects: ProjectResult[];
+}
+
+export interface TickOutcome {
+  code: number;
+  output: string;
+}
+
+export interface CycleDeps {
+  machineHome: string;
+  now: () => Date;
+  log: FileLog;
+  /** Series due state for a project root; null when the project has no database yet. */
+  due?: (root: string, now: Date) => SeriesDue[] | null;
+  /** The project's queue: jobs waiting for review, and pending jobs that can start now. Null when it has no database yet. */
+  queue?: (root: string, now: Date) => ProjectQueue | null;
+  /** Runs one project's tick. The default starts `vfrey desk tick` in the project. */
+  tickProject: (entry: IndexEntry) => Promise<TickOutcome>;
+  isMissing?: (entry: IndexEntry) => boolean;
+  isAlive?: (pid: number) => boolean;
+}
+
+/** One pass over the machine index. Never throws for a single project's trouble. */
+export async function runCycle(deps: CycleDeps): Promise<CycleReport> {
+  const now = deps.now();
+  const entries = readIndex(deps.machineHome);
+  const state = readState(deps.machineHome);
+  const results: ProjectResult[] = [];
+  const stopped = (entry: IndexEntry, outcome: Outcome, detail?: string, waiting?: number) =>
+    results.push({ id: entry.id, name: entry.name, root: entry.root, outcome, ...(detail ? { detail } : {}), ...(waiting ? { waiting } : {}) });
+  for (const entry of entries) {
+    if ((deps.isMissing ?? isMissing)(entry)) {
+      deps.log.write("warn", "project skipped: folder or vfrey.json is gone", { project: entry.name, root: entry.root });
+      stopped(entry, "missing", "folder or vfrey.json is gone");
+      state.projects[entry.id] = { lastTick: state.projects[entry.id]?.lastTick ?? null, outcome: "missing" };
+      continue;
+    }
+    let series: SeriesDue[] | null;
+    try {
+      series = (deps.due ?? projectSeriesDue)(entry.root, now);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      deps.log.write("error", "project skipped: cannot read its series", { project: entry.name, message });
+      stopped(entry, "error", message);
+      state.projects[entry.id] = { lastTick: state.projects[entry.id]?.lastTick ?? null, outcome: "error", detail: message };
+      continue;
+    }
+    const previous = state.projects[entry.id]?.lastTick ?? null;
+    let queue: ProjectQueue | null = null;
+    try {
+      queue = (deps.queue ?? projectQueue)(entry.root, now);
+    } catch {
+      queue = null;
+    }
+    let waiting = queue?.waiting ?? 0;
+    if (waiting > 0) deps.log.write("info", "jobs wait for review", { project: entry.name, waiting });
+    if (!series || series.length === 0) {
+      stopped(entry, "no series", undefined, waiting);
+      state.projects[entry.id] = { lastTick: previous, outcome: "no series", waiting };
+      continue;
+    }
+    // An approved job is pending again and has no cadence of its own: the tick that renders it must not wait for a due series.
+    if (!series.some((item) => item.due && !item.paused) && !(queue && queue.runnable > 0)) {
+      stopped(entry, "not due", undefined, waiting);
+      state.projects[entry.id] = { lastTick: previous, outcome: "not due", waiting };
+      continue;
+    }
+    const holder = liveHolder(path.join(entry.root, ".vfrey"), deps.isAlive);
+    if (holder) {
+      deps.log.write("info", "project busy: another tick holds the lock", { project: entry.name, pid: holder.pid });
+      stopped(entry, "busy", `pid ${holder.pid}`, waiting);
+      state.projects[entry.id] = { lastTick: previous, outcome: "busy", waiting };
+      continue;
+    }
+    deps.log.write("info", "ticking project", { project: entry.name, root: entry.root });
+    let outcome: TickOutcome;
+    try {
+      outcome = await deps.tickProject(entry);
+    } catch (error) {
+      outcome = { code: 1, output: error instanceof Error ? error.message : String(error) };
+    }
+    if (outcome.output.trim()) deps.log.raw(entry.name, outcome.output);
+    // The tick may have made a job that now waits for review.
+    try {
+      waiting = (deps.queue ?? projectQueue)(entry.root, deps.now())?.waiting ?? waiting;
+    } catch {
+      /* keep the count from before the tick */
+    }
+    if (outcome.code === 0) {
+      deps.log.write("info", "project ticked", { project: entry.name });
+      stopped(entry, "ticked", undefined, waiting);
+      state.projects[entry.id] = { lastTick: deps.now().toISOString(), outcome: "ticked", waiting };
+    } else if (outcome.code === LOCK_BUSY_EXIT) {
+      stopped(entry, "busy", undefined, waiting);
+      state.projects[entry.id] = { lastTick: previous, outcome: "busy", waiting };
+    } else {
+      deps.log.write("error", "project tick failed", { project: entry.name, code: outcome.code });
+      stopped(entry, "error", `exit ${outcome.code}`, waiting);
+      state.projects[entry.id] = { lastTick: previous, outcome: "error", detail: `exit ${outcome.code}`, waiting };
+    }
+  }
+  const report = { at: now.toISOString(), projects: results };
+  writeState(deps.machineHome, { ...state, pid: process.pid, lastCycle: report.at });
+  deps.log.write("info", "cycle complete", { projects: results.length, ticked: results.filter((r) => r.outcome === "ticked").length, waiting: results.reduce((sum, r) => sum + (r.waiting ?? 0), 0), skipped: results.filter((r) => r.outcome === "missing").length });
+  return report;
+}
+
+export const VFREY_BIN = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../bin/vfrey.mjs");
+
+/** The real project tick: `vfrey desk tick` as a child in the project, so its .env and data folder are its own. */
+export function spawnProjectTick(machineHome: string, env: Record<string, string | undefined>, extraArgs: string[] = [], bin: string = VFREY_BIN) {
+  const children = new Set<ReturnType<typeof spawn>>();
+  const run = (entry: IndexEntry): Promise<TickOutcome> =>
+    new Promise((resolve) => {
+      const childEnv: Record<string, string | undefined> = { ...env, VFREY_MACHINE_HOME: machineHome };
+      delete childEnv.VFREY_HOME;
+      delete childEnv.DATA_DIR;
+      const child = spawn(process.execPath, [bin, "desk", "tick", ...extraArgs], { cwd: entry.root, env: childEnv as NodeJS.ProcessEnv, stdio: ["ignore", "pipe", "pipe"] });
+      children.add(child);
+      let output = "";
+      child.stdout!.on("data", (chunk: Buffer) => (output += chunk.toString("utf8")));
+      child.stderr!.on("data", (chunk: Buffer) => (output += chunk.toString("utf8")));
+      child.on("error", (error) => resolve({ code: 1, output: error.message }));
+      child.on("close", (code) => {
+        children.delete(child);
+        resolve({ code: code ?? 1, output });
+      });
+    });
+  return { run, stopChildren: (signal: NodeJS.Signals) => children.forEach((child) => child.kill(signal)) };
+}

package/src/service/commands.ts

@@ -0,0 +1,256 @@
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, rmSync, statSync, openSync, readSync, closeSync, writeFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { resolveHome } from "../home.js";
+import { readIndex, isMissing } from "../project/index-file.js";
+import { shortHome } from "../desk/state.js";
+import { VFREY_BIN } from "./all-projects.js";
+import { projectQueue, projectSeriesDue, type SeriesDue } from "./due.js";
+import { liveHolder } from "./lock.js";
+import { logsDir, workerLogPath } from "./log-file.js";
+import { readState } from "./state.js";
+import { LAUNCHD_LABEL, SYSTEMD_UNIT, plistPath, renderPlist, renderUnit, serviceEnv, unitPath, type UnitInput } from "./units.js";
+
+export interface RunResult {
+  code: number;
+  stdout: string;
+  stderr: string;
+}
+
+/** Everything the service commands touch outside this process. Tests inject all of it. */
+export interface ServiceDeps {
+  platform: NodeJS.Platform;
+  homedir: string;
+  uid: number;
+  node: string;
+  bin: string;
+  now: () => Date;
+  /** launchctl or systemctl. Never the real one in tests. */
+  run: (command: string, args: string[]) => RunResult;
+  /** Writes the plist or unit. */
+  writeFile: (file: string, content: string) => void;
+  removeFile: (file: string) => void;
+  readFile: (file: string) => string | null;
+}
+
+export interface ServiceIo {
+  env: Record<string, string | undefined>;
+  cwd: string;
+  stdout: (text: string) => void;
+  stderr: (text: string) => void;
+  /** Stops `logs --follow`. */
+  signal?: AbortSignal;
+}
+
+export function realDeps(): ServiceDeps {
+  return {
+    platform: process.platform,
+    homedir: os.homedir(),
+    uid: process.getuid?.() ?? 0,
+    node: process.execPath,
+    bin: VFREY_BIN,
+    now: () => new Date(),
+    run: (command, args) => {
+      const result = spawnSync(command, args, { encoding: "utf8" });
+      return { code: result.status ?? 1, stdout: result.stdout ?? "", stderr: result.stderr ?? (result.error ? result.error.message : "") };
+    },
+    writeFile: (file, content) => {
+      mkdirSync(path.dirname(file), { recursive: true });
+      writeFileSync(file, content);
+    },
+    removeFile: (file) => rmSync(file, { force: true }),
+    readFile: (file) => (existsSync(file) ? readFileSync(file, "utf8") : null),
+  };
+}
+
+const fail = (io: ServiceIo, message: string, fix: string): number => {
+  io.stderr(`✗ ${message}\nFix: ${fix}\n`);
+  return 1;
+};
+
+const SUBCOMMANDS = ["install", "uninstall", "status", "logs"];
+
+type Kind = "launchd" | "systemd";
+const kindOf = (platform: NodeJS.Platform): Kind | null => (platform === "darwin" ? "launchd" : platform === "linux" ? "systemd" : null);
+
+function unitInput(deps: ServiceDeps, io: ServiceIo, machineHome: string): UnitInput {
+  return {
+    node: deps.node,
+    bin: deps.bin,
+    machineHome,
+    env: { ...serviceEnv({ HOME: deps.homedir, ...io.env }) },
+    // launchd and systemd hold this file open, so it cannot be rotated. The worker writes worker.log itself.
+    logFile: path.join(logsDir(machineHome), "service.log"),
+  };
+}
+
+interface ServiceState {
+  installed: boolean;
+  running: boolean;
+  pid: number | null;
+  file: string;
+}
+
+function serviceState(deps: ServiceDeps, kind: Kind): ServiceState {
+  if (kind === "launchd") {
+    const file = plistPath(deps.homedir);
+    const printed = deps.run("launchctl", ["print", `gui/${deps.uid}/${LAUNCHD_LABEL}`]);
+    const pid = /\bpid = (\d+)/.exec(printed.stdout)?.[1];
+    return { installed: deps.readFile(file) !== null, running: printed.code === 0 && /state = running/.test(printed.stdout), pid: pid ? Number(pid) : null, file };
+  }
+  const file = unitPath(deps.homedir);
+  const active = deps.run("systemctl", ["--user", "is-active", SYSTEMD_UNIT]);
+  const main = deps.run("systemctl", ["--user", "show", "-p", "MainPID", "--value", SYSTEMD_UNIT]);
+  const pid = Number(main.stdout.trim());
+  return { installed: deps.readFile(file) !== null, running: active.code === 0 && active.stdout.trim() === "active", pid: pid > 0 ? pid : null, file };
+}
+
+function install(io: ServiceIo, deps: ServiceDeps, kind: Kind): number {
+  const home = resolveHome(io.env, deps.homedir, io.cwd);
+  const machineHome = home.machineHome;
+  const input = unitInput(deps, io, machineHome);
+  const file = kind === "launchd" ? plistPath(deps.homedir) : unitPath(deps.homedir);
+  const content = kind === "launchd" ? renderPlist(input) : renderUnit(input);
+  const same = deps.readFile(file) === content;
+  const short = (item: string) => shortHome(item, deps.homedir);
+  if (!same) deps.writeFile(file, content);
+  io.stdout(same ? `Unchanged ${short(file)}\n` : `Wrote ${short(file)}\n`);
+  io.stdout(`  runs: ${short(deps.node)} ${short(deps.bin)} worker --all-projects\n  log:  ${short(workerLogPath(machineHome))}\n`);
+  if (kind === "launchd") {
+    const domain = `gui/${deps.uid}`;
+    deps.run("launchctl", ["bootout", `${domain}/${LAUNCHD_LABEL}`]);
+    const loaded = deps.run("launchctl", ["bootstrap", domain, file]);
+    if (loaded.code !== 0) return fail(io, `launchctl could not load the agent: ${loaded.stderr.trim() || `exit ${loaded.code}`}`, `run \`launchctl bootstrap ${domain} ${short(file)}\` and read its error.`);
+  } else {
+    deps.run("systemctl", ["--user", "daemon-reload"]);
+    const enabled = deps.run("systemctl", ["--user", "enable", "--now", SYSTEMD_UNIT]);
+    if (enabled.code !== 0) return fail(io, `systemctl could not start the worker: ${enabled.stderr.trim() || `exit ${enabled.code}`}`, "run `systemctl --user enable --now vfrey-worker.service` and read its error; `loginctl enable-linger $USER` keeps it running after logout.");
+  }
+  io.stdout("The worker now runs in the background and starts at login. Check it: npx vfrey service status\n");
+  return 0;
+}
+
+function uninstall(io: ServiceIo, deps: ServiceDeps, kind: Kind): number {
+  const state = serviceState(deps, kind);
+  if (!state.installed && !state.running) {
+    io.stdout("The background worker is not installed. Nothing to remove.\n");
+    return 0;
+  }
+  if (kind === "launchd") deps.run("launchctl", ["bootout", `gui/${deps.uid}/${LAUNCHD_LABEL}`]);
+  else deps.run("systemctl", ["--user", "disable", "--now", SYSTEMD_UNIT]);
+  deps.removeFile(state.file);
+  if (kind === "systemd") deps.run("systemctl", ["--user", "daemon-reload"]);
+  io.stdout(`Stopped the background worker and removed ${shortHome(state.file, deps.homedir)}\n`);
+  return 0;
+}
+
+const when = (iso: string | null): string => (iso ? iso.replace("T", " ").replace(/\.\d+Z$/, "Z") : "never");
+
+/** The soonest next-due time over a project's unpaused series. */
+export function projectNextDue(series: SeriesDue[] | null): string {
+  if (!series || series.length === 0) return "no series";
+  const live = series.filter((item) => !item.paused);
+  if (live.length === 0) return "paused";
+  const times = live.map((item) => item.nextDue).filter((item): item is Date => item !== null);
+  if (times.length === 0) return "not within 72 h";
+  return times.reduce((a, b) => (a < b ? a : b)).toISOString();
+}
+
+function status(io: ServiceIo, deps: ServiceDeps, kind: Kind | null, json: boolean): number {
+  const home = resolveHome(io.env, deps.homedir, io.cwd);
+  const state = kind ? serviceState(deps, kind) : null;
+  const worker = readState(home.machineHome);
+  const now = deps.now();
+  const projects = readIndex(home.machineHome).map((entry) => {
+    if (isMissing(entry)) return { name: entry.name, root: entry.root, missing: true, lastTick: worker.projects[entry.id]?.lastTick ?? null, nextDue: "missing", busy: false, waitingForReview: 0 };
+    let series: SeriesDue[] | null = null;
+    try {
+      series = projectSeriesDue(entry.root, now);
+    } catch {
+      series = null;
+    }
+    let waitingForReview = 0;
+    try {
+      waitingForReview = projectQueue(entry.root, now)?.waiting ?? 0;
+    } catch {
+      waitingForReview = 0;
+    }
+    return {
+      name: entry.name,
+      root: entry.root,
+      missing: false,
+      lastTick: worker.projects[entry.id]?.lastTick ?? null,
+      nextDue: projectNextDue(series),
+      busy: liveHolder(path.join(entry.root, ".vfrey")) !== null,
+      waitingForReview,
+    };
+  });
+  const label = !state ? "unsupported on this system" : state.running ? `running${state.pid ? ` (pid ${state.pid})` : ""}` : state.installed ? "installed, not running" : "not installed";
+  if (json) {
+    io.stdout(JSON.stringify({ service: { kind, state: label, installed: state?.installed ?? false, running: state?.running ?? false, file: state?.file ?? null }, lastCycle: worker.lastCycle, log: workerLogPath(home.machineHome), projects }, null, 2) + "\n");
+    return 0;
+  }
+  io.stdout(`Service: ${label}${state ? ` (${shortHome(state.file, deps.homedir)})` : ""}\n`);
+  if (!state || !state.installed) io.stdout("Install it: npx vfrey service install\n");
+  io.stdout(`Last cycle: ${when(worker.lastCycle)}\n`);
+  if (projects.length === 0) io.stdout("Projects: none yet. Start one: npm create vfrey@latest my-channel\n");
+  for (const p of projects) {
+    io.stdout(`  ${p.name}  ${shortHome(p.root, deps.homedir)}  ${p.missing ? "missing" : `last tick ${when(p.lastTick)}  next due ${p.nextDue}${p.busy ? "  ticking now" : ""}${p.waitingForReview ? `  ${p.waitingForReview} waiting for review` : ""}`}\n`);
+  }
+  return 0;
+}
+
+function lastLines(file: string, count: number): string {
+  const text = readFileSync(file, "utf8").split("\n");
+  if (text.at(-1) === "") text.pop();
+  return text.slice(-count).join("\n") + "\n";
+}
+
+async function logs(io: ServiceIo, deps: ServiceDeps, argv: string[]): Promise<number> {
+  const file = workerLogPath(resolveHome(io.env, deps.homedir, io.cwd).machineHome);
+  if (!existsSync(file)) return fail(io, `There is no worker log yet at ${shortHome(file, deps.homedir)}.`, "install the worker with `npx vfrey service install`, or run `npx vfrey worker --all-projects`.");
+  io.stdout(lastLines(file, 50));
+  if (!argv.includes("--follow") && !argv.includes("-f")) return 0;
+  let offset = statSync(file).size;
+  await new Promise<void>((resolve) => {
+    const timer = setInterval(() => {
+      try {
+        const size = statSync(file).size;
+        if (size < offset) offset = 0; // rotated
+        if (size > offset) {
+          const fd = openSync(file, "r");
+          const buffer = Buffer.alloc(size - offset);
+          readSync(fd, buffer, 0, buffer.length, offset);
+          closeSync(fd);
+          offset = size;
+          io.stdout(buffer.toString("utf8"));
+        }
+      } catch {
+        /* the file is being rotated; try again */
+      }
+    }, 300);
+    const done = () => {
+      clearInterval(timer);
+      resolve();
+    };
+    io.signal?.addEventListener("abort", done, { once: true });
+    process.once("SIGINT", done);
+  });
+  return 0;
+}
+
+/** `vfrey service install | uninstall | status | logs`. */
+export async function runService(argv: string[], io: ServiceIo, deps: ServiceDeps = realDeps()): Promise<number> {
+  const sub = argv[0];
+  if (!sub || !SUBCOMMANDS.includes(sub)) return fail(io, `Unknown service command "${sub ?? ""}".`, `use one of: ${SUBCOMMANDS.join(", ")}.`);
+  if (sub === "logs") return logs(io, deps, argv);
+  const kind = kindOf(deps.platform);
+  if (!kind) {
+    if (sub === "status") return status(io, deps, null, argv.includes("--json"));
+    return fail(io, `The background service is supported on macOS and Linux, not ${deps.platform}.`, "run `npx vfrey worker --all-projects` in a terminal and leave it open.");
+  }
+  if (sub === "install") return install(io, deps, kind);
+  if (sub === "uninstall") return uninstall(io, deps, kind);
+  return status(io, deps, kind, argv.includes("--json"));
+}

package/src/service/due.ts

@@ -0,0 +1,82 @@
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { cadenceDecision, localDayKey } from "@vfrey/contracts";
+import { validateCadence } from "../config.js";
+import { applyDeskAccount } from "../desk/overlay.js";
+import { deskAccounts } from "../desk/series.js";
+import { Store } from "../queue/store.js";
+
+export interface SeriesDue {
+  id: string;
+  paused: boolean;
+  due: boolean;
+  reason: string;
+  /** When the series is next due (now when due). Null when paused, or not within the next 72 hours. */
+  nextDue: Date | null;
+}
+
+/** The first minute within 72 hours at which the cadence lets a video start. */
+export function nextDueAt(cadence: Parameters<typeof cadenceDecision>[0]["cadence"], times: Date[], now: Date): Date | null {
+  for (let minute = 0; minute <= 72 * 60; minute += 1) {
+    const at = new Date(now.getTime() + minute * 60_000);
+    const day = localDayKey(at, cadence.timezone);
+    const decision = cadenceDecision({
+      cadence,
+      now: at,
+      lastPublishedAt: times[0] ?? null,
+      postsOnLocalDay: times.filter((time) => localDayKey(time, cadence.timezone) === day).length,
+    });
+    if (decision.due) return at;
+  }
+  return null;
+}
+
+/** Every series of a project and whether it is due. Reads the project's own database; null when it has none yet. */
+export function projectSeriesDue(root: string, now: Date): SeriesDue[] | null {
+  const file = path.join(root, ".vfrey", "pipeline.sqlite");
+  if (!existsSync(file)) return null;
+  const store = new Store(file);
+  try {
+    return deskAccounts(store).map((base): SeriesDue => {
+      const overlay = store.deskOverlay(base.id);
+      const account = overlay ? applyDeskAccount(base, overlay) : base;
+      if (store.seriesPaused(account.id)) return { id: account.id, paused: true, due: false, reason: "paused", nextDue: null };
+      const fault = validateCadence(account.cadence);
+      if (fault) return { id: account.id, paused: false, due: false, reason: `invalid_cadence: ${fault}`, nextDue: null };
+      const times = store.videoTimes(account.id);
+      const day = localDayKey(now, account.cadence.timezone);
+      const decision = cadenceDecision({
+        cadence: account.cadence,
+        now,
+        lastPublishedAt: times[0] ?? null,
+        postsOnLocalDay: times.filter((time) => localDayKey(time, account.cadence.timezone) === day).length,
+      });
+      return { id: account.id, paused: false, due: decision.due, reason: decision.reason, nextDue: decision.due ? now : nextDueAt(account.cadence, times, now) };
+    });
+  } finally {
+    store.close();
+  }
+}
+
+export interface ProjectQueue {
+  /** Jobs that wait for a person to approve or reject them (spec 015 D). They hold no worker. */
+  waiting: number;
+  /** Pending jobs that can start now, such as one that was just approved. A tick is worth running for them even when no series is due. */
+  runnable: number;
+}
+
+/** What a project's queue holds besides the cadence. Null when the project has no database yet. */
+export function projectQueue(root: string, now: Date): ProjectQueue | null {
+  const file = path.join(root, ".vfrey", "pipeline.sqlite");
+  if (!existsSync(file)) return null;
+  const store = new Store(file);
+  try {
+    const count = (sql: string, ...args: string[]) => Number((store.db.prepare(sql).get(...args) as { n: number }).n);
+    return {
+      waiting: count(`SELECT COUNT(*) AS n FROM jobs WHERE status = 'awaiting_review'`),
+      runnable: count(`SELECT COUNT(*) AS n FROM jobs WHERE kind = 'pipeline' AND status = 'pending' AND run_after <= ?`, now.toISOString()),
+    };
+  } finally {
+    store.close();
+  }
+}

package/src/service/lock.ts

@@ -0,0 +1,101 @@
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import path from "node:path";
+
+export const LOCK_FILE = "worker.lock";
+
+export interface LockHolder {
+  pid: number;
+  started: string;
+}
+
+export type LockResult = { ok: true; release: () => void } | { ok: false; holder: LockHolder };
+
+export interface LockOptions {
+  pid?: number;
+  now?: () => Date;
+  /** Whether a process is alive. Injected in tests. */
+  isAlive?: (pid: number) => boolean;
+}
+
+export function pidAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    // EPERM means the process exists but belongs to someone else.
+    return (error as NodeJS.ErrnoException).code === "EPERM";
+  }
+}
+
+export function lockPath(dataDir: string): string {
+  return path.join(dataDir, LOCK_FILE);
+}
+
+/** The holder written in the lock file, or null when it is missing or unreadable. */
+export function readLock(dataDir: string): LockHolder | null {
+  try {
+    const parsed = JSON.parse(readFileSync(lockPath(dataDir), "utf8")) as Partial<LockHolder>;
+    if (typeof parsed.pid === "number" && typeof parsed.started === "string") return { pid: parsed.pid, started: parsed.started };
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+/** The holder when a live process holds the lock; null when free or stale. */
+export function liveHolder(dataDir: string, isAlive: (pid: number) => boolean = pidAlive): LockHolder | null {
+  const holder = readLock(dataDir);
+  return holder && isAlive(holder.pid) ? holder : null;
+}
+
+/**
+ * Takes `<dataDir>/worker.lock` for this process. A lock whose process is gone (or whose file is unreadable)
+ * is stale and is taken over. The same lock is used by the worker, `tick`, and `desk tick`, so they never run
+ * the same project at once.
+ */
+export function acquireLock(dataDir: string, options: LockOptions = {}): LockResult {
+  const pid = options.pid ?? process.pid;
+  const isAlive = options.isAlive ?? pidAlive;
+  const file = lockPath(dataDir);
+  const body = JSON.stringify({ pid, started: (options.now?.() ?? new Date()).toISOString() }) + "\n";
+  mkdirSync(dataDir, { recursive: true });
+  for (let attempt = 0; attempt < 3; attempt += 1) {
+    try {
+      writeFileSync(file, body, { flag: "wx" });
+      let released = false;
+      const release = () => {
+        if (released) return;
+        released = true;
+        // Only remove a lock that is still ours.
+        if (readLock(dataDir)?.pid === pid) rmSync(file, { force: true });
+      };
+      return { ok: true, release };
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+    }
+    const holder = readLock(dataDir);
+    if (holder && holder.pid !== pid && isAlive(holder.pid)) return { ok: false, holder };
+    // Stale: the holder died, or the file is not a lock. Remove it and try again.
+    rmSync(file, { force: true });
+  }
+  const holder = readLock(dataDir);
+  return { ok: false, holder: holder ?? { pid: 0, started: "unknown" } };
+}
+
+/** Takes the lock and drops it when this process exits, however it exits. */
+export function acquireLockForProcess(dataDir: string, options: LockOptions = {}): LockResult {
+  const result = acquireLock(dataDir, options);
+  if (result.ok) {
+    process.once("exit", result.release);
+  }
+  return result;
+}
+
+export const LOCK_BUSY_EXIT = 75;
+
+export function busyMessage(holder: LockHolder): { message: string; fix: string } {
+  return {
+    message: `Another vfrey tick is already running for this project (pid ${holder.pid}, since ${holder.started}).`,
+    fix: "wait for it to finish; the background worker and a manual tick never run the same project at once.",
+  };
+}

package/src/service/log-file.ts

@@ -0,0 +1,56 @@
+import { appendFileSync, existsSync, mkdirSync, renameSync, rmSync, statSync } from "node:fs";
+import path from "node:path";
+import { redact } from "@vfrey/contracts";
+
+export const MAX_LOG_BYTES = 5 * 1024 * 1024;
+export const KEEP_LOGS = 3;
+
+export const logsDir = (machineHome: string): string => path.join(machineHome, "logs");
+export const workerLogPath = (machineHome: string): string => path.join(logsDir(machineHome), "worker.log");
+
+/** worker.log -> worker.log.1 -> .2 -> .3; the oldest is dropped. */
+export function rotate(file: string, keep: number = KEEP_LOGS): void {
+  rmSync(`${file}.${keep}`, { force: true });
+  for (let n = keep - 1; n >= 1; n -= 1) {
+    if (existsSync(`${file}.${n}`)) renameSync(`${file}.${n}`, `${file}.${n + 1}`);
+  }
+  if (existsSync(file)) renameSync(file, `${file}.1`);
+}
+
+export interface FileLog {
+  write(level: string, message: string, fields?: Record<string, unknown>): void;
+  /** Appends raw text (a child's output), line by line, tagged. */
+  raw(tag: string, text: string): void;
+}
+
+/** A JSON-lines log with size rotation. Secrets are redacted. Never throws: a log must not stop the worker. */
+export function createFileLog(file: string, options: { maxBytes?: number; keep?: number; now?: () => Date; echo?: (line: string) => void } = {}): FileLog {
+  const maxBytes = options.maxBytes ?? MAX_LOG_BYTES;
+  const append = (line: string) => {
+    try {
+      mkdirSync(path.dirname(file), { recursive: true });
+      let size = 0;
+      try {
+        size = statSync(file).size;
+      } catch {
+        /* first write */
+      }
+      if (size > 0 && size + Buffer.byteLength(line) > maxBytes) rotate(file, options.keep ?? KEEP_LOGS);
+      appendFileSync(file, line);
+      options.echo?.(line);
+    } catch {
+      /* ignore */
+    }
+  };
+  const ts = () => (options.now?.() ?? new Date()).toISOString();
+  return {
+    write(level, message, fields = {}) {
+      append(redact(JSON.stringify({ ts: ts(), level, message, ...fields })) + "\n");
+    },
+    raw(tag, text) {
+      for (const line of text.split("\n")) {
+        if (line.trim()) append(redact(JSON.stringify({ ts: ts(), level: "info", message: line, source: tag })) + "\n");
+      }
+    },
+  };
+}