@vfrey/vfrey 0.0.1 → 1.0.0-beta.1

package/src/product/keys.ts

@@ -0,0 +1,67 @@
+import { chmod, mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+export const KEY_PLATFORMS = ["youtube", "tiktok", "instagram", "facebook"] as const;
+export type KeyPlatform = (typeof KEY_PLATFORMS)[number];
+
+export type KeyFile = Partial<Record<KeyPlatform, string>>;
+
+export function parseKeyFile(raw: string): KeyFile {
+  if (!raw.trim()) return {};
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw new Error("Key file is not JSON.");
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error("Key file must be an object.");
+  }
+  const out: KeyFile = {};
+  for (const platform of KEY_PLATFORMS) {
+    const value = (parsed as Record<string, unknown>)[platform];
+    if (typeof value === "string" && value.trim()) out[platform] = value;
+  }
+  return out;
+}
+
+export function keyPresence(keys: KeyFile): Record<KeyPlatform, boolean> {
+  return {
+    youtube: Boolean(keys.youtube),
+    tiktok: Boolean(keys.tiktok),
+    instagram: Boolean(keys.instagram),
+    facebook: Boolean(keys.facebook),
+  };
+}
+
+export function hasPlatformKey(keys: KeyFile, platform: string): boolean {
+  if (!KEY_PLATFORMS.includes(platform as KeyPlatform)) return false;
+  return Boolean(keys[platform as KeyPlatform]);
+}
+
+export function withKey(keys: KeyFile, platform: string, value: string): KeyFile {
+  if (!KEY_PLATFORMS.includes(platform as KeyPlatform)) {
+    throw new Error(`Unknown platform ${platform}.`);
+  }
+  const next: KeyFile = { ...keys };
+  const trimmed = value.trim();
+  if (!trimmed) delete next[platform as KeyPlatform];
+  else next[platform as KeyPlatform] = trimmed;
+  return next;
+}
+
+export async function readKeys(filePath: string): Promise<KeyFile> {
+  try {
+    return parseKeyFile(await readFile(filePath, "utf8"));
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return {};
+    throw error;
+  }
+}
+
+export async function writeKeys(filePath: string, keys: KeyFile): Promise<void> {
+  await mkdir(path.dirname(filePath), { recursive: true });
+  const body = `${JSON.stringify(keys)}\n`;
+  await writeFile(filePath, body, { mode: 0o600 });
+  await chmod(filePath, 0o600);
+}

package/src/product/paths.ts

@@ -0,0 +1,18 @@
+import path from "node:path";
+import { dataDirFor } from "../home.js";
+
+export function productDir(env: NodeJS.ProcessEnv): string {
+  return env.PRODUCT_HOME ? path.resolve(env.PRODUCT_HOME) : path.join(dataDirFor(env), "product");
+}
+
+export function keyFile(dir: string): string {
+  return path.join(dir, "keys.json");
+}
+
+export function insightFile(dir: string): string {
+  return path.join(dir, "insights.json");
+}
+
+export function configFile(dir: string): string {
+  return path.join(dir, "config.json");
+}

package/src/product/probes.ts

@@ -0,0 +1,88 @@
+import { execFileSync } from "node:child_process";
+import { constants, existsSync, accessSync } from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+import { headlessShellMissing, onPath, PACKAGE_ROOT, resolveHeadlessShell } from "../render/chrome.js";
+import type { EngineProbes } from "./engines.js";
+
+type Env = Record<string, string | undefined>;
+
+export const FRAMEY_ENTRY = path.join(PACKAGE_ROOT, "vendor/framey/bin/framey.mjs");
+
+/** Why the vendored Framey renderer cannot run here, or null when it can. */
+export function frameyRendererProblem(): string | null {
+  if (!existsSync(FRAMEY_ENTRY)) return "the Framey renderer is missing from this install; reinstall vfrey";
+  try {
+    createRequire(FRAMEY_ENTRY).resolve("puppeteer-core");
+  } catch {
+    return "the Framey renderer's dependencies are not installed; run npm install in the vfrey folder";
+  }
+  return null;
+}
+
+/** Why an HTML engine has no Chrome or ffmpeg here, or null when it has both. */
+export function renderEnvProblem(env: Env, cwd: string): string | null {
+  if (!onPath("ffmpeg", env)) return "ffmpeg is not on PATH; install ffmpeg";
+  if (!resolveHeadlessShell(env, cwd)) {
+    return "Chrome Headless Shell is not downloaded yet; run `npx remotion browser ensure`";
+  }
+  return null;
+}
+
+function isExecutable(file: string): boolean {
+  try {
+    accessSync(file, constants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** The upstream HyperFrames CLI to run: HYPERFRAMES_BIN, a local install, or one on PATH. */
+export function hyperframesCandidates(env: Env, cwd: string): string[] {
+  const found: string[] = [];
+  if (env.HYPERFRAMES_BIN) found.push(env.HYPERFRAMES_BIN);
+  for (const root of [cwd, PACKAGE_ROOT]) found.push(path.join(root, "node_modules/.bin/hyperframes"));
+  for (const dir of (env.PATH ?? "").split(path.delimiter)) if (dir) found.push(path.join(dir, "hyperframes"));
+  return found.filter((file) => isExecutable(file));
+}
+
+/** The command line that runs a HyperFrames entry: a script goes through node, a binary runs as is. */
+export function commandFor(bin: string): { command: string; args: string[] } {
+  return /\.(mjs|cjs|js)$/.test(bin) ? { command: process.execPath, args: [bin] } : { command: bin, args: [] };
+}
+
+/** The first HyperFrames CLI that answers `--version`, with the version line. */
+export function hyperframesCli(env: Env, cwd: string): { bin: string; version: string } | null {
+  for (const bin of hyperframesCandidates(env, cwd)) {
+    const { command, args } = commandFor(bin);
+    try {
+      const out = execFileSync(command, [...args, "--version"], { env: env as NodeJS.ProcessEnv, timeout: 8000, stdio: ["ignore", "pipe", "ignore"] });
+      return { bin, version: out.toString().trim().split(/\r?\n/)[0] ?? "" };
+    } catch {
+      /* not a working CLI; try the next one */
+    }
+  }
+  return null;
+}
+
+/** Why Framey has no ffmpeg here, or null. A missing Chrome Headless Shell is not a problem: the first render downloads it. */
+function frameyEnvProblem(env: Env): string | null {
+  return onPath("ffmpeg", env) ? null : "ffmpeg is not on PATH; install ffmpeg";
+}
+
+/** Everything the engine list needs, probed without a network call. */
+export function probeEnginesSync(env: Env, cwd: string = process.cwd()): EngineProbes {
+  return {
+    hyperframesCli: hyperframesCli(env, cwd) !== null,
+    comfyReachable: false,
+    frameyProblem: frameyRendererProblem() ?? frameyEnvProblem(env),
+    frameyDownloadsChrome: headlessShellMissing(env, cwd),
+    renderEnvProblem: renderEnvProblem(env, cwd),
+  };
+}
+
+/** Probes for the dashboard and the render stage. ComfyUI is not wired, so no server is asked. */
+export async function defaultProbes(env: Env, cwd: string = process.cwd()): Promise<EngineProbes> {
+  return probeEnginesSync(env, cwd);
+}

package/src/product/push-flow.ts

@@ -0,0 +1,90 @@
+export type DescriptionChoice = "type" | "auto";
+export type ThumbnailChoice = "same" | "address" | "generate";
+
+export interface PushInput {
+  platform: string;
+  hasKey: boolean;
+  description?: DescriptionChoice | null;
+  descriptionText?: string | null;
+  thumbnail?: ThumbnailChoice | null;
+  thumbnailAddress?: string | null;
+}
+
+export type PushPhase = "stopped" | "ask" | "ready";
+
+export interface PushDecision {
+  phase: PushPhase;
+  message: string;
+  uploadAttempted: false;
+  question?: "description" | "description-text" | "thumbnail" | "thumbnail-address";
+}
+
+const DESCRIPTION = new Set<DescriptionChoice>(["type", "auto"]);
+const THUMBNAIL = new Set<ThumbnailChoice>(["same", "address", "generate"]);
+
+export function decidePush(input: PushInput): PushDecision {
+  const platform = input.platform.trim().toLowerCase() || "youtube";
+  const name = platform === "youtube" ? "YouTube" : platform;
+  if (!input.hasKey) {
+    return {
+      phase: "stopped",
+      uploadAttempted: false,
+      message: `The ${name} key is not configured. This video cannot be pushed there.`,
+    };
+  }
+  if (!input.description || !DESCRIPTION.has(input.description)) {
+    return {
+      phase: "ask",
+      uploadAttempted: false,
+      question: "description",
+      message: "Description: type one, or auto-generate?",
+    };
+  }
+  if (input.description === "type" && !input.descriptionText?.trim()) {
+    return {
+      phase: "ask",
+      uploadAttempted: false,
+      question: "description-text",
+      message: "Type the description to use on the post.",
+    };
+  }
+  if (!input.thumbnail || !THUMBNAIL.has(input.thumbnail)) {
+    return {
+      phase: "ask",
+      uploadAttempted: false,
+      question: "thumbnail",
+      message: "Thumbnail: use the same thumbnail, give an address, or generate one?",
+    };
+  }
+  if (input.thumbnail === "address" && !input.thumbnailAddress?.trim()) {
+    return {
+      phase: "ask",
+      uploadAttempted: false,
+      question: "thumbnail-address",
+      message: "Give the address of the thumbnail.",
+    };
+  }
+  const description =
+    input.description === "auto" ? "an auto-generated description" : "the description you typed";
+  const thumbnail =
+    input.thumbnail === "same"
+      ? "the same thumbnail"
+      : input.thumbnail === "generate"
+        ? "a generated thumbnail"
+        : "the thumbnail at the address you gave";
+  return {
+    phase: "ready",
+    uploadAttempted: false,
+    message: `Ready to publish to ${name} with ${description} and ${thumbnail}.`,
+  };
+}
+
+export async function runPush(
+  input: PushInput,
+  upload: () => Promise<void>,
+): Promise<PushDecision & { uploaded: boolean }> {
+  const decision = decidePush(input);
+  if (decision.phase !== "ready") return { ...decision, uploaded: false };
+  await upload();
+  return { ...decision, uploaded: true };
+}

package/src/product/render-video.ts

@@ -0,0 +1,21 @@
+import { stat } from "node:fs/promises";
+import type { RenderProps } from "@vfrey/contracts";
+import { assertCanRender, type EngineAvailability, type EngineId, type EngineSpec } from "./engines.js";
+
+export interface RenderRequest {
+  engine: EngineSpec;
+  availability: EngineAvailability;
+  /** Why the engine is unavailable, for the refusal. */
+  reason?: string | null;
+  outputPath: string;
+  props: RenderProps;
+  renderLocal: (outputPath: string, props: RenderProps, engine: EngineId) => Promise<void>;
+}
+
+export async function renderChosenEngine(request: RenderRequest): Promise<{ outputPath: string; bytes: number }> {
+  assertCanRender(request.engine, request.availability, request.reason);
+  await request.renderLocal(request.outputPath, request.props, request.engine.id);
+  const info = await stat(request.outputPath);
+  if (info.size <= 0) throw new Error("Render wrote an empty file.");
+  return { outputPath: request.outputPath, bytes: info.size };
+}

package/src/product/short.ts

@@ -0,0 +1,62 @@
+import { TEMPLATES } from "@vfrey/contracts";
+import type { Beat, RenderProps, TemplateId } from "@vfrey/contracts";
+
+export const SHORT_FRAME = { width: 1080, height: 1920, fps: 30 } as const;
+
+const ROLES = ["hook", "setup", "turn", "evidence", "cta"] as const;
+const WEIGHTS = [0.18, 0.22, 0.22, 0.2, 0.18];
+
+export function parseComposition(value: string | null | undefined): TemplateId {
+  if (!value?.trim()) return "KineticType";
+  const found = (Object.keys(TEMPLATES) as TemplateId[]).find((id) => id.toLowerCase() === value.trim().toLowerCase());
+  if (!found) throw new Error("Unknown composition. Choose KineticType, SignalBoard, or EditorialSplit.");
+  return found;
+}
+
+function round3(value: number): number {
+  return Math.round(value * 1000) / 1000;
+}
+
+export function durationInBand(composition: TemplateId, seconds: number): boolean {
+  const spec = TEMPLATES[composition];
+  return seconds >= spec.durationMinSec && seconds <= spec.durationMaxSec;
+}
+
+/** On-screen package for a vertical short. The hook caption is the subject. */
+export function buildShort(subject: string, composition: TemplateId = "KineticType"): RenderProps {
+  const trimmed = subject.trim();
+  if (!trimmed) throw new Error("A subject is required.");
+  const spec = TEMPLATES[composition];
+  let used = 0;
+  const captions = [
+    trimmed,
+    `What ${trimmed} does`,
+    `How to use ${trimmed}`,
+    `Why ${trimmed} is useful`,
+    `Start with ${trimmed}`,
+  ];
+  const beats: Beat[] = WEIGHTS.map((weight, index) => {
+    const seconds =
+      index === WEIGHTS.length - 1 ? round3(spec.durationTargetSec - used) : round3(spec.durationTargetSec * weight);
+    used = round3(used + seconds);
+    return { role: ROLES[index]!, text: captions[index]!, caption: captions[index]!, seconds };
+  });
+  const durationSec = round3(beats.reduce((sum, beat) => sum + beat.seconds, 0));
+  if (!durationInBand(composition, durationSec)) {
+    throw new Error(`${composition} duration ${durationSec}s is outside its published band.`);
+  }
+  const palette = spec.palettes[0];
+  if (!palette) throw new Error(`${composition} has no palette.`);
+  return {
+    templateId: composition,
+    title: trimmed,
+    hook: trimmed,
+    beats,
+    palette,
+    captionStyle: spec.captionStyle,
+    pacing: spec.pacing,
+    voiceoverFile: null,
+    layoutSeed: 2,
+    durationSec,
+  };
+}

package/src/product/update.ts

@@ -0,0 +1,32 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { packageVersion } from "../skill-install.js";
+
+/** The folder holding this package's package.json, wherever the caller's shell is. */
+export function updateInstallRoot(): string {
+  const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../..");
+  // Installed from npm, this package sits at <project>/node_modules/@vfrey/vfrey; the update runs in <project>.
+  const marker = `${path.sep}node_modules${path.sep}`;
+  const at = root.lastIndexOf(marker);
+  return at === -1 ? root : root.slice(0, at);
+}
+
+/** Commands the owner runs to refresh the app and the installed skills. The agent-neutral skill refresh is `vfrey skill install --agent <agent>`. */
+export function updateCommands(version: string = packageVersion()): readonly string[] {
+  // A prerelease (1.0.0-beta.0) is matched only by exact pins, so a beta follows the beta tag.
+  const prerelease = /^\d+\.\d+\.\d+-/.test(version);
+  return [
+    "claude plugin update vfrey@vfrey",
+    prerelease ? "npm install @vfrey/vfrey@beta" : "npm install",
+  ];
+}
+
+export function formatUpdatePlan(apply: boolean, version: string = packageVersion()): string {
+  const lines = [
+    "Update the vfrey app and the skills:",
+    ...updateCommands(version).map((command) => `- ${command}`),
+    "Not on Claude Code? Refresh the skill for your agent instead: npx @vfrey/vfrey skill install --agent codex|grok|cursor|gemini (or all).",
+  ];
+  if (!apply) lines.push("Printed only. Pass --apply to run them.");
+  return lines.join("\n");
+}

package/src/project/canonical.ts

@@ -0,0 +1,14 @@
+import { realpathSync } from "node:fs";
+import path from "node:path";
+
+/** The real path of `p` (symlinks resolved), or its absolute form when it does not exist yet. Compare paths only in this form. */
+export function canonicalPath(p: string): string {
+  const abs = path.resolve(p);
+  try {
+    return realpathSync.native(abs);
+  } catch {
+    // Not there yet: canonicalize the nearest existing parent so a new folder behind a symlink still compares equal.
+    const parent = path.dirname(abs);
+    return parent === abs ? abs : path.join(canonicalPath(parent), path.basename(abs));
+  }
+}

package/src/project/commands.ts

@@ -0,0 +1,177 @@
+import { existsSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { DatabaseSync } from "node:sqlite";
+import { resolveHome } from "../home.js";
+import { ENGINE_IDS } from "../product/engines.js";
+import { Store } from "../queue/store.js";
+import { dashboardStatus } from "./dashboard-status.js";
+import { isMissing, pruneIndex, readIndex, registerProject, touchProject } from "./index-file.js";
+import { canonicalPath } from "./canonical.js";
+import { ProjectError } from "./marker.js";
+import { importDesk } from "./migrate.js";
+import { dayStamp } from "./names.js";
+import { projectJson, projectNotice } from "./notice.js";
+import { scaffoldProject } from "./scaffold.js";
+import { liveHolder } from "../service/lock.js";
+import { readState } from "../service/state.js";
+import { listVideos } from "./videos.js";
+
+export interface ProjectIo {
+  env: Record<string, string | undefined>;
+  cwd: string;
+  homedir?: string;
+  stdout: (text: string) => void;
+  stderr: (text: string) => void;
+}
+
+function flag(argv: string[], name: string): string | null {
+  const at = argv.indexOf(name);
+  if (at < 0) return null;
+  const value = argv[at + 1];
+  return value === undefined || value.startsWith("--") ? "" : value;
+}
+
+const fail = (io: ProjectIo, message: string, fix: string): number => {
+  io.stderr(`✗ ${message}\nFix: ${fix}\n`);
+  return 1;
+};
+
+function length(seconds: number | null): string {
+  if (seconds === null) return "-";
+  const whole = Math.round(seconds);
+  return `${Math.floor(whole / 60)}:${String(whole % 60).padStart(2, "0")}`;
+}
+
+/** `vfrey init [--name NAME] [--engine ENGINE] [--from DIR]`. */
+export function runInit(argv: string[], io: ProjectIo): number {
+  const from = flag(argv, "--from");
+  if (from === "") return fail(io, "--from needs a folder.", "for example `npx vfrey init --from ~/.vfrey`.");
+  const name = flag(argv, "--name");
+  if (name === "") return fail(io, "--name needs a name.", "for example `npx vfrey init --name my-channel`.");
+  const engine = flag(argv, "--engine");
+  if (engine !== null && !(ENGINE_IDS as readonly string[]).includes(engine)) {
+    return fail(io, `"${engine}" is not an engine.`, `choose ${ENGINE_IDS.join(", ")}.`);
+  }
+  const home = resolveHome(io.env, io.homedir ?? os.homedir(), io.cwd);
+  try {
+    const result = scaffoldProject(canonicalPath(io.cwd), { name: name ?? undefined, engine: engine ?? undefined });
+    registerProject(home.machineHome, result.project);
+    const what = result.existing ? `Repaired the vfrey project ${result.project.name}` : `Started the vfrey project ${result.project.name}`;
+    io.stdout(`${what} in ${result.project.root}\n`);
+    for (const item of result.created) io.stdout(`  ${result.existing ? "repaired" : "+"} ${item}\n`);
+    for (const item of result.kept) io.stdout(`  kept ${item}\n`);
+    if (from !== null) {
+      const counts = importDesk(from, result.project);
+      io.stdout(
+        `Imported ${path.resolve(from)}: ${counts.jobs} runs (${counts.otherRows} other rows), ${counts.videos} videos, ${counts.transcripts} transcripts, ${counts.scenes} scenes.\n`,
+      );
+      if (counts.alreadyImported > 0) io.stdout(`  ${counts.alreadyImported} videos were already imported and were left alone.\n`);
+      if (counts.withoutVideo > 0) io.stdout(`  ${counts.withoutVideo} runs have no video file (failed, pending or deleted); their rows were copied.\n`);
+      io.stdout("The source was not changed.\n");
+    }
+    io.stdout("Videos land in videos/. Make one: npx vfrey tick --now --about \"<subject>\"\n");
+    return 0;
+  } catch (error) {
+    if (error instanceof ProjectError) return fail(io, error.reason, error.fix);
+    throw error;
+  }
+}
+
+/** `vfrey videos [--json] [--limit N]`, newest first. */
+export function runVideos(argv: string[], io: ProjectIo): number {
+  const limitRaw = flag(argv, "--limit");
+  let limit: number | undefined;
+  if (limitRaw !== null) {
+    limit = Number(limitRaw);
+    if (!Number.isInteger(limit) || limit < 1) return fail(io, `--limit needs a whole number of 1 or more, not "${limitRaw}".`, "for example `npx vfrey videos --limit 5`.");
+  }
+  const home = resolveHome(io.env, io.homedir ?? os.homedir(), io.cwd);
+  const notice = projectNotice(home);
+  if (notice) io.stderr(notice);
+  if (home.project) touchProject(home.machineHome, home.project);
+  const store = new Store(path.join(home.dataDir, "pipeline.sqlite"));
+  let videos;
+  try {
+    videos = listVideos(store.db, home.dataDir, limit);
+  } finally {
+    store.close();
+  }
+  if (argv.includes("--json")) {
+    io.stdout(
+      JSON.stringify(
+        { project: projectJson(home), dataDir: home.dataDir, videos: videos.map((v) => ({ id: v.id, date: v.date, title: v.title, durationSec: v.durationSec, path: v.path })) },
+        null,
+        2,
+      ) + "\n",
+    );
+    return 0;
+  }
+  if (videos.length === 0) {
+    io.stdout("No videos yet. Make one: npx vfrey tick --now --about \"<subject>\"\n");
+    return 0;
+  }
+  for (const v of videos) io.stdout(`${dayStamp(new Date(v.date))}  ${length(v.durationSec).padStart(5)}  ${v.title ?? "(untitled)"}  ${v.path}\n`);
+  return 0;
+}
+
+function lastVideoOf(root: string): { title: string | null; date: string; path: string } | null {
+  const dataDir = path.join(root, ".vfrey");
+  const file = path.join(dataDir, "pipeline.sqlite");
+  if (!existsSync(file)) return null;
+  let db: DatabaseSync | null = null;
+  try {
+    db = new DatabaseSync(file, { readOnly: true });
+    const [first] = listVideos(db, dataDir, 1);
+    return first ? { title: first.title, date: first.date, path: first.path } : null;
+  } catch {
+    return null;
+  } finally {
+    db?.close();
+  }
+}
+
+/** `vfrey projects [--prune] [--json]`: the machine index. */
+export async function runProjects(argv: string[], io: ProjectIo): Promise<number> {
+  const home = resolveHome(io.env, io.homedir ?? os.homedir(), io.cwd);
+  if (home.project) touchProject(home.machineHome, home.project);
+  const pruned = argv.includes("--prune") ? pruneIndex(home.machineHome) : [];
+  const entries = readIndex(home.machineHome).sort((a, b) => b.lastUsed.localeCompare(a.lastUsed));
+  const statuses = await Promise.all(entries.map((entry) => (isMissing(entry) ? Promise.resolve({ status: "unknown" as const, url: null }) : dashboardStatus(entry.root, io.env))));
+  const workerState = readState(home.machineHome);
+  const workerOf = (entry: (typeof entries)[number]): { state: string; lastTick: string | null } => {
+    const lastTick = workerState.projects[entry.id]?.lastTick ?? null;
+    if (isMissing(entry)) return { state: "-", lastTick };
+    if (liveHolder(path.join(entry.root, ".vfrey"))) return { state: "ticking", lastTick };
+    return { state: lastTick ? `last tick ${dayStamp(new Date(lastTick))}` : "never ticked", lastTick };
+  };
+  const rows = entries.map((entry, at) => ({
+      worker: workerOf(entry),
+      id: entry.id,
+      name: entry.name,
+      root: entry.root,
+      lastUsed: entry.lastUsed,
+      missing: isMissing(entry),
+      lastVideo: isMissing(entry) ? null : lastVideoOf(entry.root),
+      dashboard: statuses[at]!.status,
+      dashboardUrl: statuses[at]!.url,
+    }));
+  if (argv.includes("--json")) {
+    io.stdout(JSON.stringify({ projects: rows, pruned: pruned.map((p) => ({ id: p.id, name: p.name, root: p.root })) }, null, 2) + "\n");
+    return 0;
+  }
+  for (const p of pruned) io.stdout(`Removed ${p.name} (${p.root}): the folder is gone.\n`);
+  if (rows.length === 0) {
+    io.stdout("No projects yet. Start one: npm create vfrey@latest my-channel\n");
+    return 0;
+  }
+  for (const r of rows) {
+    if (r.missing) {
+      io.stdout(`${r.name}  ${r.root}  missing (run \`npx vfrey projects --prune\` to drop it)\n`);
+      continue;
+    }
+    const last = r.lastVideo ? `last video ${dayStamp(new Date(r.lastVideo.date))} ${r.lastVideo.title ?? "(untitled)"}` : "no videos yet";
+    io.stdout(`${r.name}  ${r.root}  ${last}  dashboard ${r.dashboard}${r.dashboardUrl ? ` ${r.dashboardUrl}` : ""}  worker ${r.worker.state}\n`);
+  }
+  return 0;
+}

package/src/project/dashboard-status.ts

@@ -0,0 +1,28 @@
+import path from "node:path";
+import { canonicalPath } from "./canonical.js";
+import { findDashboard } from "../dashboard-link.js";
+import { MARKER_FILE, readMarker } from "./marker.js";
+import { existsSync } from "node:fs";
+
+/** Whether a project's dashboard is listening: its `.vfrey/dashboard.json` and `GET /api/state` naming this project's id. */
+export type DashboardStatus = "up" | "down" | "unknown";
+
+export interface DashboardInfo {
+  status: DashboardStatus;
+  url: string | null;
+}
+
+/** "up" with the URL, "down", or "unknown" when the project's marker cannot be read. */
+export async function dashboardStatus(rootPath: string, env: Record<string, string | undefined> = process.env): Promise<DashboardInfo> {
+  const projectRoot = canonicalPath(rootPath);
+  if (!existsSync(path.join(projectRoot, MARKER_FILE))) return { status: "unknown", url: null };
+  let id: string;
+  let name: string;
+  try {
+    ({ id, name } = readMarker(projectRoot));
+  } catch {
+    return { status: "unknown", url: null };
+  }
+  const origin = await findDashboard({ dataDir: path.join(projectRoot, ".vfrey"), project: { id, name } }, env);
+  return origin ? { status: "up", url: origin } : { status: "down", url: null };
+}

package/src/project/discover.ts

@@ -0,0 +1,19 @@
+import path from "node:path";
+import { canonicalPath } from "./canonical.js";
+import { hasMarker, projectAt, type Project } from "./marker.js";
+
+/** The nearest folder at or above `cwd` that holds `vfrey.json`, the way git finds `.git`. */
+export function findProjectRoot(cwd: string): string | null {
+  let dir = canonicalPath(cwd);
+  for (;;) {
+    if (hasMarker(dir)) return dir;
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+export function findProject(cwd: string): Project | null {
+  const root = findProjectRoot(cwd);
+  return root ? projectAt(root) : null;
+}