@vfrey/vfrey 0.0.1 → 1.0.0-beta.0

package/src/project/index-file.ts

@@ -0,0 +1,73 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { canonicalPath } from "./canonical.js";
+
+export interface IndexEntry {
+  id: string;
+  name: string;
+  root: string;
+  lastUsed: string;
+}
+
+export const INDEX_FILE = "projects.json";
+
+const indexFile = (machineHome: string) => path.join(machineHome, INDEX_FILE);
+
+/** The machine index. Never the source of truth for a project's data; a missing or broken file reads as empty. */
+export function readIndex(machineHome: string): IndexEntry[] {
+  try {
+    const parsed = JSON.parse(readFileSync(indexFile(machineHome), "utf8")) as unknown;
+    if (!Array.isArray(parsed)) return [];
+    const valid = parsed.filter(
+      (item): item is IndexEntry =>
+        !!item && typeof item === "object" && typeof item.id === "string" && typeof item.name === "string" && typeof item.root === "string" && typeof item.lastUsed === "string",
+    );
+    // Entries written through a symlinked path are read as their real root; two that meet there are one project (newest wins).
+    const byRoot = new Map<string, IndexEntry>();
+    for (const item of valid) {
+      const root = canonicalPath(item.root);
+      const seen = byRoot.get(root);
+      if (!seen || item.lastUsed >= seen.lastUsed) byRoot.set(root, { ...item, root });
+    }
+    return [...byRoot.values()];
+  } catch {
+    return [];
+  }
+}
+
+function writeIndex(machineHome: string, entries: IndexEntry[]): void {
+  mkdirSync(machineHome, { recursive: true });
+  const file = indexFile(machineHome);
+  const tmp = `${file}.${process.pid}.tmp`;
+  writeFileSync(tmp, JSON.stringify(entries, null, 2) + "\n");
+  renameSync(tmp, file);
+}
+
+/** Adds the project, or refreshes its name, root and time when its id or root is already listed. */
+export function registerProject(machineHome: string, project: { id: string; name: string; root: string }, now: Date = new Date()): void {
+  const root = canonicalPath(project.root);
+  const entries = readIndex(machineHome).filter((entry) => entry.id !== project.id && entry.root !== root);
+  entries.push({ id: project.id, name: project.name, root, lastUsed: now.toISOString() });
+  writeIndex(machineHome, entries);
+}
+
+/** A command resolved this project: note it. Never fails the command. */
+export function touchProject(machineHome: string, project: { id: string; name: string; root: string }, now: Date = new Date()): void {
+  try {
+    registerProject(machineHome, project, now);
+  } catch {
+    /* the index is a convenience */
+  }
+}
+
+export function isMissing(entry: IndexEntry): boolean {
+  return !existsSync(path.join(entry.root, "vfrey.json"));
+}
+
+/** Drops every entry whose root is gone. Returns what it dropped. */
+export function pruneIndex(machineHome: string): IndexEntry[] {
+  const entries = readIndex(machineHome);
+  const gone = entries.filter(isMissing);
+  if (gone.length > 0) writeIndex(machineHome, entries.filter((entry) => !isMissing(entry)));
+  return gone;
+}

package/src/project/marker.ts

@@ -0,0 +1,87 @@
+import { randomUUID } from "node:crypto";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { canonicalPath } from "./canonical.js";
+
+import { ENGINE_IDS } from "../product/engines.js";
+
+export const MARKER_FILE = "vfrey.json";
+
+export interface ProjectMarker {
+  version: 1;
+  name: string;
+  id: string;
+  /** This project's preferred render engine: beats the machine default, loses to `--engine` and a series engine. */
+  engine?: string;
+}
+
+/** A vfrey project: the folder that holds `vfrey.json`. */
+export interface Project {
+  name: string;
+  id: string;
+  /** The engine named in vfrey.json, if any. */
+  engine?: string;
+  root: string;
+  /** `<root>/.vfrey`, where the database, logs and per-job copies live. */
+  dataDir: string;
+}
+
+/** A broken `vfrey.json`. The CLI prints it in the refusal style. */
+export class ProjectError extends Error {
+  constructor(
+    readonly reason: string,
+    readonly fix: string,
+  ) {
+    super(`${reason} Fix: ${fix}`);
+    this.name = "ProjectError";
+  }
+}
+
+export function validateMarker(value: unknown): ProjectMarker | string {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return "it is not a JSON object";
+  const marker = value as Record<string, unknown>;
+  if (marker.version !== 1) return `"version" must be 1`;
+  if (typeof marker.name !== "string" || !marker.name.trim()) return `"name" must be a non-empty string`;
+  if (typeof marker.id !== "string" || !marker.id.trim()) return `"id" must be a non-empty string`;
+  if (marker.engine !== undefined && !(typeof marker.engine === "string" && (ENGINE_IDS as readonly string[]).includes(marker.engine))) {
+    return `"engine" must be one of ${ENGINE_IDS.join(", ")}`;
+  }
+  return { ...marker, version: 1, name: marker.name.trim(), id: marker.id.trim() } as ProjectMarker;
+}
+
+/** Reads and checks `<root>/vfrey.json`. Throws ProjectError when the file is there but wrong. */
+export function readMarker(root: string): ProjectMarker {
+  const file = path.join(root, MARKER_FILE);
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(readFileSync(file, "utf8"));
+  } catch {
+    throw new ProjectError(`${file} is not valid JSON.`, `fix the file, or delete it if this folder is not a vfrey project.`);
+  }
+  const checked = validateMarker(parsed);
+  if (typeof checked === "string") {
+    throw new ProjectError(
+      `${file} is not a vfrey project file: ${checked}.`,
+      checked.startsWith('"engine"') ? `set "engine" to one of ${ENGINE_IDS.join(", ")}, or remove it to follow the machine default.` : `use {"version": 1, "name": "my-channel", "id": "<uuid>"}.`,
+    );
+  }
+  return checked;
+}
+
+export function writeMarker(root: string, marker: ProjectMarker): void {
+  writeFileSync(path.join(root, MARKER_FILE), JSON.stringify(marker, null, 2) + "\n");
+}
+
+export function newMarker(name: string): ProjectMarker {
+  return { version: 1, name, id: randomUUID() };
+}
+
+export function hasMarker(root: string): boolean {
+  return existsSync(path.join(root, MARKER_FILE));
+}
+
+export function projectAt(rootPath: string): Project {
+  const root = canonicalPath(rootPath);
+  const marker = readMarker(root);
+  return { name: marker.name, id: marker.id, ...(marker.engine ? { engine: marker.engine } : {}), root, dataDir: path.join(root, ".vfrey") };
+}

package/src/project/migrate.ts

@@ -0,0 +1,201 @@
+import { cpSync, existsSync, mkdirSync, mkdtempSync, rmSync, statSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { DatabaseSync } from "node:sqlite";
+import { Store } from "../queue/store.js";
+import { canonicalPath } from "./canonical.js";
+import { ProjectError, type Project } from "./marker.js";
+import { readableVideoPath } from "./names.js";
+import { videoFile } from "./videos.js";
+
+export interface ImportCounts {
+  /** Jobs newly copied into the project's database this run. */
+  jobs: number;
+  /** Rows copied in all other tables. */
+  otherRows: number;
+  videos: number;
+  transcripts: number;
+  scenes: number;
+  /** Runs whose video was already in the project from an earlier import. */
+  alreadyImported: number;
+  /** Runs that never had a video file on disk. */
+  withoutVideo: number;
+}
+
+type Payload = {
+  content?: { title?: unknown; outputPath?: unknown; voiceoverPath?: unknown; voiceoverScript?: unknown } | null;
+  scene?: { source?: unknown; dir?: unknown } | null;
+  [key: string]: unknown;
+};
+
+const quote = (name: string) => `"${name.replace(/"/g, '""')}"`;
+
+/**
+ * Copies a machine desk (a folder with `pipeline.sqlite`, `renders/` and `scenes/`) into a project: the database rows with
+ * their job ids, each render as `videos/YYYY-MM-DD <title>.mp4` with its transcript, and the stored scene copies into
+ * `.vfrey/scenes/`. Stored video paths become project-relative. The source is never written: the database is read through
+ * a consistent `VACUUM INTO` copy, and a source another process is writing is refused. Running it again adds nothing.
+ */
+export function importDesk(sourceArg: string, project: Project): ImportCounts {
+  const source = canonicalPath(sourceArg);
+  const sourceDb = path.join(source, "pipeline.sqlite");
+  if (!existsSync(sourceDb)) throw new ProjectError(`${source} has no pipeline.sqlite, so there is nothing to import.`, "pass the data folder, for example `--from ~/.vfrey`.");
+  if (canonicalPath(project.dataDir) === source) throw new ProjectError("--from points at this project's own data folder.", "pass the machine desk or another data folder.");
+
+  const counts: ImportCounts = { jobs: 0, otherRows: 0, videos: 0, transcripts: 0, scenes: 0, alreadyImported: 0, withoutVideo: 0 };
+  mkdirSync(project.dataDir, { recursive: true });
+  const work = mkdtempSync(path.join(project.dataDir, "import-"));
+  const copy = path.join(work, "source.sqlite");
+  try {
+    snapshot(sourceDb, copy, source);
+    const store = new Store(path.join(project.dataDir, "pipeline.sqlite"));
+    try {
+      const ids = mergeTables(store.db, copy, counts);
+      moveFiles(store.db, ids, source, project, counts);
+    } finally {
+      store.close();
+    }
+  } finally {
+    rmSync(work, { recursive: true, force: true });
+  }
+  return counts;
+}
+
+/** A consistent copy of the source database. Refuses when another process holds the write lock. */
+function snapshot(sourceDb: string, dest: string, source: string): void {
+  let db: DatabaseSync | null = null;
+  try {
+    db = new DatabaseSync(sourceDb);
+    db.exec("PRAGMA busy_timeout = 0");
+    try {
+      db.exec("BEGIN IMMEDIATE");
+      db.exec("ROLLBACK");
+    } catch (error) {
+      if (/locked|busy/i.test(String((error as Error).message))) {
+        throw new ProjectError(`${source} is busy: another vfrey process is writing to its database.`, "stop its dashboard or worker (or wait for its tick to finish), then run this again.");
+      }
+      throw error;
+    }
+    db.exec("PRAGMA busy_timeout = 5000");
+    db.exec(`VACUUM INTO '${dest.replace(/'/g, "''")}'`);
+  } catch (error) {
+    if (error instanceof ProjectError) throw error;
+    if (/locked|busy/i.test(String((error as Error).message))) {
+      throw new ProjectError(`${source} is busy: another vfrey process is writing to its database.`, "stop its dashboard or worker, then run this again.");
+    }
+    throw new ProjectError(`${sourceDb} could not be read as a vfrey database (${(error as Error).message}).`, "pass a data folder made by vfrey.");
+  } finally {
+    try {
+      db?.close();
+    } catch {
+      /* closing a refused connection */
+    }
+  }
+}
+
+/** INSERT OR IGNORE every table of the copy into the project's database, by shared column names. */
+function mergeTables(db: DatabaseSync, copy: string, counts: ImportCounts): Set<string> {
+  db.exec(`ATTACH DATABASE '${copy.replace(/'/g, "''")}' AS src`);
+  try {
+    const ids = new Set((db.prepare(`SELECT id FROM src.jobs`).all() as Array<{ id: string }>).map((r) => r.id));
+    const first = (db.prepare(`SELECT COUNT(*) AS n FROM main.jobs j WHERE j.id IN (SELECT id FROM src.jobs)`).get() as { n: number }).n === 0;
+    const tables = (db.prepare(`SELECT name FROM src.sqlite_master WHERE type = 'table' AND name NOT LIKE 'sqlite_%' ORDER BY name`).all() as Array<{ name: string }>).map((t) => t.name);
+    db.exec("BEGIN");
+    try {
+      for (const table of tables) {
+        const mine = db.prepare(`PRAGMA main.table_info(${quote(table)})`).all() as Array<{ name: string; pk: number }>;
+        if (mine.length === 0) continue;
+        const theirs = new Set((db.prepare(`PRAGMA src.table_info(${quote(table)})`).all() as Array<{ name: string }>).map((c) => c.name));
+        const columns = mine.map((c) => c.name).filter((c) => theirs.has(c));
+        if (columns.length === 0) continue;
+        // A table with no key would gain the same rows again on a re-run, so it is copied once, on the first import.
+        const keyed = mine.some((c) => c.pk > 0) || (db.prepare(`PRAGMA main.index_list(${quote(table)})`).all() as Array<{ unique: number }>).some((i) => i.unique === 1);
+        if (!keyed && !first) continue;
+        const list = columns.map(quote).join(", ");
+        const before = (db.prepare(`SELECT COUNT(*) AS n FROM main.${quote(table)}`).get() as { n: number }).n;
+        db.exec(`INSERT OR IGNORE INTO main.${quote(table)} (${list}) SELECT ${list} FROM src.${quote(table)}`);
+        const added = (db.prepare(`SELECT COUNT(*) AS n FROM main.${quote(table)}`).get() as { n: number }).n - before;
+        if (table === "jobs") counts.jobs += added;
+        else counts.otherRows += added;
+      }
+      db.exec("COMMIT");
+    } catch (error) {
+      db.exec("ROLLBACK");
+      throw error;
+    }
+    return ids;
+  } finally {
+    db.exec("DETACH DATABASE src");
+  }
+}
+
+/** Copy each pipeline run's video, transcript and scene into the project and rewrite its stored paths. */
+function moveFiles(db: DatabaseSync, ids: Set<string>, source: string, project: Project, counts: ImportCounts): void {
+  const videos = path.join(project.root, "videos");
+  const scenesOut = path.join(project.dataDir, "scenes");
+  mkdirSync(videos, { recursive: true });
+  const rows = db.prepare(`SELECT id, payload, finished_at, updated_at, created_at FROM jobs WHERE kind = 'pipeline' ORDER BY created_at, id`).all() as Array<{
+    id: string;
+    payload: string;
+    finished_at: string | null;
+    updated_at: string;
+    created_at: string;
+  }>;
+  const update = db.prepare(`UPDATE jobs SET payload = ? WHERE id = ?`);
+  for (const row of rows) {
+    let payload: Payload;
+    try {
+      payload = JSON.parse(row.payload) as Payload;
+    } catch {
+      continue;
+    }
+    // Only runs that came from the source: a project's own runs keep their paths.
+    if (!ids.has(row.id)) continue;
+    let changed = false;
+
+    const stored = payload.content?.outputPath;
+    const relative = typeof stored === "string" && !path.isAbsolute(stored) ? path.resolve(project.root, stored) : null;
+    if (relative && existsSync(relative)) {
+      counts.alreadyImported += 1;
+    } else {
+      const mp4 = videoFile(source, row.id, stored);
+      if (!mp4) {
+        counts.withoutVideo += 1;
+      } else {
+        const when = new Date(row.finished_at || row.updated_at || row.created_at);
+        const title = typeof payload.content?.title === "string" && payload.content.title.trim() ? payload.content.title : "video";
+        const dest = readableVideoPath(videos, Number.isNaN(when.getTime()) ? new Date() : when, title);
+        cpSync(mp4, dest);
+        counts.videos += 1;
+        const text = mp4.replace(/\.mp4$/, ".txt");
+        const script = typeof payload.content?.voiceoverScript === "string" ? payload.content.voiceoverScript.trim() : "";
+        if (existsSync(text)) {
+          cpSync(text, dest.replace(/\.mp4$/, ".txt"));
+          counts.transcripts += 1;
+        } else if (script) {
+          writeFileSync(dest.replace(/\.mp4$/, ".txt"), `${script}\n`);
+          counts.transcripts += 1;
+        }
+        payload.content = { ...(payload.content ?? {}), outputPath: path.relative(project.root, dest).split(path.sep).join("/") };
+        changed = true;
+      }
+    }
+    // The voice file stays behind in the source desk; nothing reads it after the render.
+    if (payload.content && typeof payload.content.voiceoverPath === "string" && !existsSync(path.resolve(project.root, payload.content.voiceoverPath))) {
+      payload.content.voiceoverPath = null;
+      changed = true;
+    }
+
+    const sceneFrom = path.join(source, "scenes", row.id);
+    const sceneTo = path.join(scenesOut, row.id);
+    if (existsSync(sceneFrom) && statSync(sceneFrom).isDirectory() && !existsSync(sceneTo)) {
+      mkdirSync(scenesOut, { recursive: true });
+      cpSync(sceneFrom, sceneTo, { recursive: true });
+      counts.scenes += 1;
+    }
+    if (payload.scene && payload.scene.source === "agent" && existsSync(sceneTo) && payload.scene.dir !== sceneTo) {
+      payload.scene = { ...payload.scene, dir: sceneTo };
+      changed = true;
+    }
+    if (changed) update.run(JSON.stringify(payload), row.id);
+  }
+}

package/src/project/names.ts

@@ -0,0 +1,27 @@
+import { existsSync } from "node:fs";
+import path from "node:path";
+
+const UNSAFE = /[\\/:*?"<>|\u0000-\u001f]/g;
+
+/** A title that is safe in a file name on every system: no `/ : \ * ? " < > |`, at most 80 characters. */
+export function safeTitle(title: string): string {
+  const cleaned = title.replace(UNSAFE, " ").replace(/\s+/g, " ").trim();
+  const cut = Array.from(cleaned).slice(0, 80).join("").trim().replace(/^\.+/, "").replace(/[. ]+$/, "");
+  return cut || "video";
+}
+
+/** The local calendar day as YYYY-MM-DD. */
+export function dayStamp(date: Date): string {
+  const pad = (n: number) => String(n).padStart(2, "0");
+  return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}`;
+}
+
+/** `<videosDir>/YYYY-MM-DD <title>.mp4`, or with ` (2)`, ` (3)` ... when the mp4 or its transcript is already there. */
+export function readableVideoPath(videosDir: string, date: Date, title: string): string {
+  const base = `${dayStamp(date)} ${safeTitle(title)}`;
+  for (let n = 1; ; n += 1) {
+    const stem = n === 1 ? base : `${base} (${n})`;
+    const mp4 = path.join(videosDir, `${stem}.mp4`);
+    if (!existsSync(mp4) && !existsSync(path.join(videosDir, `${stem}.txt`))) return mp4;
+  }
+}

package/src/project/notice.ts

@@ -0,0 +1,16 @@
+import type { ResolvedHome } from "../home.js";
+
+export const NOT_IN_PROJECT_NOTICE = "Not in a vfrey project; using the machine desk ~/.vfrey. Start one: npm create vfrey@latest my-channel\n";
+
+/**
+ * The stderr line for a command that makes or lists videos outside a project. Null in a project, and null when an env var
+ * chose the data folder: then "the machine desk ~/.vfrey" would not be true.
+ */
+export function projectNotice(home: ResolvedHome): string | null {
+  return home.source === "machine" ? NOT_IN_PROJECT_NOTICE : null;
+}
+
+/** The `project` field of a `--json` document. */
+export function projectJson(home: ResolvedHome): { name: string; root: string } | null {
+  return home.project ? { name: home.project.name, root: home.project.root } : null;
+}

package/src/project/open.ts

@@ -0,0 +1,88 @@
+import { existsSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { deskOf } from "../dashboard-link.js";
+import { browserDisabled, ensureDashboard, openBrowser, type EnsureOptions, type EnsureResult } from "../dashboard-start.js";
+import { resolveHome } from "../home.js";
+import { Store } from "../queue/store.js";
+import { isMissing, readIndex } from "./index-file.js";
+import { projectJson, projectNotice } from "./notice.js";
+import { listVideos, type VideoRow } from "./videos.js";
+import type { ProjectIo } from "./commands.js";
+
+export interface OpenIo extends ProjectIo {
+  /** Test hooks. The CLI omits them. */
+  ensure?: (options: EnsureOptions) => Promise<EnsureResult>;
+  openBrowser?: (url: string) => void;
+}
+
+const fail = (io: ProjectIo, message: string, fix: string): number => {
+  io.stderr(`✗ ${message}\nFix: ${fix}\n`);
+  return 1;
+};
+
+type Target = { kind: "none" } | { kind: "run"; id: string } | { kind: "error"; message: string; fix: string };
+
+/** A run id, or a video named by its path or its title (as `vfrey videos` shows them). */
+export function resolveTarget(arg: string | undefined, videos: VideoRow[], cwd: string, runIds: (id: string) => boolean): Target {
+  if (!arg) return { kind: "none" };
+  if (runIds(arg)) return { kind: "run", id: arg };
+  const asPath = path.resolve(cwd, arg);
+  const byPath = videos.find((v) => v.path === asPath || v.path === arg || path.basename(v.path) === arg || path.basename(v.path, ".mp4") === arg);
+  if (byPath) return { kind: "run", id: byPath.id };
+  const wanted = arg.toLowerCase();
+  const exact = videos.filter((v) => v.title?.toLowerCase() === wanted);
+  if (exact.length > 0) return { kind: "run", id: exact[0]!.id };
+  const partial = videos.filter((v) => v.title?.toLowerCase().includes(wanted) || path.basename(v.path).toLowerCase().includes(wanted));
+  if (partial.length === 1) return { kind: "run", id: partial[0]!.id };
+  if (partial.length > 1) {
+    return { kind: "error", message: `"${arg}" matches ${partial.length} videos: ${partial.slice(0, 5).map((v) => v.title ?? v.id).join("; ")}.`, fix: "pass the run id or the full path from `npx vfrey videos`." };
+  }
+  return { kind: "error", message: `No run or video matches "${arg}".`, fix: "run `npx vfrey videos` for the list, then pass a run id, a path, or a title." };
+}
+
+/** `vfrey open [run|video] [--no-browser] [--json]`: reuse or start this desk's dashboard, open it, print the URL. */
+export async function runOpen(argv: string[], io: OpenIo): Promise<number> {
+  const home = resolveHome(io.env, io.homedir ?? os.homedir(), io.cwd);
+  const arg = argv.find((a) => !a.startsWith("--"));
+  const notice = projectNotice(home);
+  const desk = deskOf(home);
+  const dbFile = path.join(home.dataDir, "pipeline.sqlite");
+  let videos: VideoRow[] = [];
+  const runIds = new Set<string>();
+  let hasRuns = false;
+  if (existsSync(dbFile)) {
+    const store = new Store(dbFile);
+    try {
+      videos = listVideos(store.db, home.dataDir);
+      for (const row of store.db.prepare(`SELECT id FROM jobs`).all() as Array<{ id: string }>) runIds.add(row.id);
+      hasRuns = store.db.prepare(`SELECT 1 FROM jobs WHERE kind = 'pipeline' LIMIT 1`).get() !== undefined;
+    } finally {
+      store.close();
+    }
+  }
+  // Outside a project, with nothing on the machine desk, there is no way to know which project is meant. Do not guess.
+  if (home.source === "machine" && !hasRuns) {
+    const projects = readIndex(home.machineHome).filter((p) => !isMissing(p));
+    if (projects.length > 0) {
+      const list = projects.map((p) => `  ${p.name}  ${p.root}`).join("\n");
+      io.stderr(`✗ Not in a vfrey project, and the machine desk has no videos. Projects on this machine:\n${list}\n`);
+      io.stderr("Fix: cd into one of them, then run `npx vfrey open`.\n");
+      return 1;
+    }
+  }
+  if (notice) io.stderr(notice);
+  const target = resolveTarget(arg, videos, io.cwd, (id) => runIds.has(id));
+  if (target.kind === "error") return fail(io, target.message, target.fix);
+  const ensure = io.ensure ?? ensureDashboard;
+  const result = await ensure({ desk, env: io.env, cwd: io.cwd });
+  if (!result.ok) return fail(io, result.message, result.fix);
+  const url = target.kind === "run" ? `${result.origin}/runs/${target.id}` : `${result.origin}/`;
+  if (!browserDisabled(argv, io.env)) (io.openBrowser ?? openBrowser)(url);
+  if (argv.includes("--json")) {
+    io.stdout(JSON.stringify({ url, started: result.started, project: projectJson(home), runId: target.kind === "run" ? target.id : null }, null, 2) + "\n");
+    return 0;
+  }
+  io.stdout(`${url}\n`);
+  return 0;
+}

package/src/project/scaffold.ts

@@ -0,0 +1,112 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { agentSkillTarget } from "../skill-agents.js";
+import { installSkillIfMissing, packageVersion } from "../skill-install.js";
+import { hasMarker, newMarker, projectAt, readMarker, writeMarker, type Project } from "./marker.js";
+import { CLAUDE_MD, GEMINI_MD, agentsMd, slug } from "./templates.js";
+
+export const GITIGNORE_LINES = ["node_modules/", ".vfrey/", "videos/"];
+
+export interface ScaffoldResult {
+  project: Project;
+  /** Paths (relative to the root) this call created. Empty when everything was already there. */
+  created: string[];
+  /** Paths that were already there and were left alone. */
+  kept: string[];
+  /** True when the folder was already a vfrey project and was only repaired. */
+  existing: boolean;
+}
+
+export const PACKAGE_NAME = "@vfrey/vfrey";
+
+/** The scripts a project's package.json gets: the commands a person or an agent types most. */
+export const PROJECT_SCRIPTS: Record<string, string> = {
+  dashboard: "vfrey dashboard",
+  open: "vfrey open",
+  doctor: "vfrey doctor",
+  videos: "vfrey videos",
+};
+
+/** package.json: private, depends on this exact package version, with the four scripts. An existing file only gains what is missing. */
+function ensurePackageJson(root: string, name: string): "written" | "repaired" | "kept" {
+  const file = path.join(root, "package.json");
+  if (!existsSync(file)) {
+    const pkg = { name: slug(name), private: true, version: "0.0.0", scripts: PROJECT_SCRIPTS, dependencies: { [PACKAGE_NAME]: packageVersion() } };
+    writeFileSync(file, JSON.stringify(pkg, null, 2) + "\n");
+    return "written";
+  }
+  let pkg: { scripts?: Record<string, string>; dependencies?: Record<string, string> };
+  try {
+    pkg = JSON.parse(readFileSync(file, "utf8"));
+    if (!pkg || typeof pkg !== "object" || Array.isArray(pkg)) return "kept";
+  } catch {
+    return "kept";
+  }
+  let changed = false;
+  pkg.dependencies ??= {};
+  if (!pkg.dependencies[PACKAGE_NAME] && !(pkg as { devDependencies?: Record<string, string> }).devDependencies?.[PACKAGE_NAME]) {
+    pkg.dependencies[PACKAGE_NAME] = packageVersion();
+    changed = true;
+  }
+  pkg.scripts ??= {};
+  for (const [key, value] of Object.entries(PROJECT_SCRIPTS)) {
+    if (pkg.scripts[key] === undefined) {
+      pkg.scripts[key] = value;
+      changed = true;
+    }
+  }
+  if (changed) writeFileSync(file, JSON.stringify(pkg, null, 2) + "\n");
+  return changed ? "repaired" : "kept";
+}
+
+/**
+ * Writes the project layout into `root`: the marker, `.vfrey/`, `scenes/`, `scripts/`, `videos/`, `.gitignore`,
+ * package.json, AGENTS.md, CLAUDE.md, GEMINI.md and the skill for Claude Code (`.claude/skills/vfrey`) and for every other agent
+ * (`.agents/skills/vfrey`). Idempotent: an existing file is never overwritten and is reported as kept; a missing one is
+ * written. An existing `.gitignore` only gains missing lines, and an existing package.json only gains what is missing.
+ */
+export function scaffoldProject(root: string, options: { name?: string; engine?: string } = {}): ScaffoldResult {
+  const created: string[] = [];
+  const kept: string[] = [];
+  mkdirSync(root, { recursive: true });
+  const existing = hasMarker(root);
+  if (!existing) {
+    const marker = newMarker(options.name?.trim() || path.basename(path.resolve(root)));
+    writeMarker(root, options.engine ? ({ ...marker, engine: options.engine } as typeof marker) : marker);
+    created.push("vfrey.json");
+  }
+  for (const dir of [".vfrey", "scenes", "scripts", "videos"]) {
+    const full = path.join(root, dir);
+    if (!existsSync(full)) {
+      mkdirSync(full, { recursive: true });
+      created.push(`${dir}/`);
+    }
+  }
+  const ignore = path.join(root, ".gitignore");
+  const have = existsSync(ignore) ? readFileSync(ignore, "utf8") : null;
+  const present = new Set((have ?? "").split(/\r?\n/).map((line) => line.trim()));
+  const missing = GITIGNORE_LINES.filter((line) => !present.has(line));
+  if (missing.length > 0) {
+    const prefix = have && have.length > 0 && !have.endsWith("\n") ? "\n" : "";
+    writeFileSync(ignore, (have ?? "") + prefix + missing.join("\n") + "\n");
+    created.push(".gitignore");
+  } else kept.push(".gitignore");
+  const project = projectAt(root);
+  const engine = options.engine ?? (readMarker(root) as { engine?: unknown }).engine;
+  const record = (rel: string, result: "written" | "repaired" | "kept") => (result === "kept" ? kept : created).push(rel);
+  const writeIfMissing = (rel: string, text: string) => {
+    const file = path.join(root, rel);
+    if (existsSync(file)) return record(rel, "kept");
+    writeFileSync(file, text);
+    record(rel, "written");
+  };
+  record("package.json", ensurePackageJson(root, project.name));
+  writeIfMissing("AGENTS.md", agentsMd(project.name, typeof engine === "string" ? engine : undefined));
+  writeIfMissing("CLAUDE.md", CLAUDE_MD);
+  writeIfMissing("GEMINI.md", GEMINI_MD);
+  for (const agent of ["claude", "codex"] as const) {
+    const dir = agentSkillTarget(agent, {}, root, true);
+    record(`${path.relative(root, dir).split(path.sep).join("/")}/`, installSkillIfMissing(dir));
+  }
+  return { project, created, kept, existing };
+}

package/src/project/templates.ts

@@ -0,0 +1,42 @@
+/** The text of the files `init` writes into a project. Short on purpose: an agent reads these on every session. */
+
+export function agentsMd(name: string, engine?: string): string {
+  return `# ${name}: a vfrey project
+
+This folder makes short videos. The person talks to you; you run \`npx vfrey\`. They do not need to know any command.
+
+## Make a video
+
+Use the vfrey skill (\`.claude/skills/vfrey\` or \`.agents/skills/vfrey\`) if you have it. If not, this is the flow:
+
+1. Write the script yourself: \`scripts/<idea>.json\` (\`npx vfrey tick --script-template\` prints an example). Plain and accurate, 6 to 10 short lines, nothing invented.
+2. Design a scene for the idea in \`scenes/<idea>/\` (\`npx vfrey scene init scenes/<idea>\`). No fixed templates: two ideas should not look alike. Preview with \`npx vfrey render --scene scenes/<idea> --engine ${engine ?? "<engine>"} --script scripts/<idea>.json --frame 2.5 out.png\`.
+3. \`npx vfrey tick --now --about "<subject>" --script scripts/<idea>.json --scene scenes/<idea> --engine ${engine ?? "<engine>"}\`
+4. Tell the person the path of the video in \`videos/\` and the \`See it:\` link.
+
+## Commands
+
+- \`npx vfrey open [run|video]\`: show things. Opens this project's dashboard and prints its URL.
+- \`npx vfrey videos\`: finished videos, newest first, with paths.
+- \`npx vfrey projects\`: the other projects on this machine.
+- \`npx vfrey doctor\`: check the machine. Run it first when something fails.
+
+\`npx vfrey --help\` lists the rest.
+
+## Where things go
+
+\`scenes/\`, \`scripts/\`, \`videos/\` (finished videos, \`YYYY-MM-DD <title>.mp4\` with a transcript; do not rename or move them). \`.vfrey/\` is vfrey's data: do not edit it.
+`;
+}
+
+export const CLAUDE_MD = "@AGENTS.md\n";
+/** Gemini CLI reads GEMINI.md, not AGENTS.md; it supports @file imports. */
+export const GEMINI_MD = "@AGENTS.md\n";
+
+export function slug(name: string): string {
+  const cleaned = name
+    .toLowerCase()
+    .replace(/[^a-z0-9._-]+/g, "-")
+    .replace(/^[._-]+|[._-]+$/g, "");
+  return cleaned || "vfrey-project";
+}