Skip to content

Open source CapCut alternative.

TypeScript
25.7 KB
Raw Blame
import fsSync from "node:fs";
import { isDeliveryName } from "../lib/exportDelivery";
import { cp, mkdir, readdir, readFile, rm, stat, writeFile } from "node:fs/promises";
import path from "node:path";
import { defaultNames } from "@/cut/lib/defaultNames";
import { resolveParent, settleParents, subtreeOf } from "@/cut/lib/folderTree";
import { timelineEnd } from "@/cut/lib/timelineEnd";
import type { Aspect, ProjectDoc, ProjectFolder, ProjectSummary } from "@/cut/lib/types";
import { DEFAULT_LOCALE, type Locale } from "@/i18n/locales";
import { UserError } from "@/cut/lib/userError";
import { cutDataRoot } from "./dataDir";
import { assertLocalRuntime } from "./local-only";
import { exists, uniqueName, writeJsonAtomic } from "./util";

/** Projects live directly under the data root, shared by every account that
 * signs in on this Mac; each project is one folder holding project.json, its
 * raw media files, and its exports. The folder is named after the project —
 * that's what the user sees in Finder — and follows renames; the stable API
 * id lives in project.json, and resolveDirName maps id to folder. */
const projectsRoot = () => path.join(cutDataRoot(), "projects");
// Project folders are grouping metadata only; it lives beside the project dirs
// as a plain file, and the project scans skip non-directories.
const foldersIndex = () => path.join(projectsRoot(), "folders.json");

const ID_RE = /^[a-z0-9][a-z0-9-]{2,40}$/;

/** The Finder-safe folder name for a display name: path-hostile characters
 * become spaces, leading dots go (a hidden project folder helps nobody), and
 * an empty result falls back to `fallback`. */
function dirNameFrom(name: string, fallback: string): string {
  const cleaned = name
    .replace(/[/\\:*?"<>|]/g, " ")
    .replace(/\s+/g, " ")
    .trim()
    .replace(/^\.+/, "")
    .slice(0, 60)
    .trim();
  return cleaned || fallback;
}

// Names inside projects/ that belong to the app itself, never to a project
// folder — a project literally named "folders.json" takes a suffix instead of
// sitting where writeFolders renames its index in.
const RESERVED_DIR_NAMES = new Set(["folders.json", "folders.json.bak"]);
const isReservedDirName = (name: string) => RESERVED_DIR_NAMES.has(name.toLowerCase());

/** Claim a free folder name by creating it — mkdir is the atomic check, so two
 * concurrent creates with the same name can't share a folder. */
async function claimDir(want: string): Promise<string> {
  await mkdir(projectsRoot(), { recursive: true });
  for (let n = 1; ; n++) {
    const candidate = n === 1 ? want : `${want} ${n}`;
    if (isReservedDirName(candidate)) continue;
    try {
      fsSync.mkdirSync(path.join(projectsRoot(), candidate));
      return candidate;
    } catch (err) {
      if ((err as NodeJS.ErrnoException).code !== "EEXIST") throw err;
    }
  }
}

/** A folder's project doc, read for identity: project.json first, then the
 * .bak mirror, so one truncated save never makes the project unresolvable
 * while a good backup sits beside it. (readProject does the actual restore on
 * open; this only has to see the doc.) */
function readDocSyncAt(dir: string): { id?: string; name?: string } | null {
  for (const file of ["project.json", "project.json.bak"]) {
    try {
      return JSON.parse(fsSync.readFileSync(path.join(dir, file), "utf8")) as {
        id?: string;
        name?: string;
      };
    } catch {
      // Missing or unreadable; try the mirror.
    }
  }
  return null;
}

/** Sync twin of util.writeJsonAtomic for the startup reconcile: unique temp,
 * .bak written from the committed bytes, then renamed in. */
function writeDocSync(docFile: string, doc: unknown) {
  const json = JSON.stringify(doc, null, 2);
  const tmp = `${docFile}.${crypto.randomUUID().slice(0, 8)}.tmp`;
  fsSync.writeFileSync(tmp, json);
  try {
    fsSync.writeFileSync(`${docFile}.bak`, json);
  } catch {
    // Best-effort mirror, like writeJsonAtomic.
  }
  fsSync.renameSync(tmp, docFile);
}

// id -> folder, maintained by every create/rename/delete in this process (the
// engine is the only writer). An entry remembers the folder's inode and is
// trusted only while the folder at that name still has it, so a folder
// swapped, replaced, or trashed in Finder can't satisfy a stale entry — the
// lookup falls through to a rescan instead of touching another project's
// folder. Unresolvable ids are remembered briefly (missCache) so a dead tab
// autosaving to a deleted project can't hammer the full scan on every request.
const dirIndex = new Map<string, { name: string; ino: number }>();
const missCache = new Map<string, number>();
const MISS_TTL_MS = 2000;

function setDirIndex(id: string, name: string) {
  try {
    dirIndex.set(id, { name, ino: fsSync.statSync(path.join(projectsRoot(), name)).ino });
    missCache.delete(id);
  } catch {
    dirIndex.delete(id);
  }
}

function resolveDirName(id: string): string | null {
  const root = projectsRoot();
  const cached = dirIndex.get(id);
  if (cached) {
    try {
      if (fsSync.statSync(path.join(root, cached.name)).ino === cached.ino) return cached.name;
    } catch {
      // Folder gone; rescan below.
    }
    dirIndex.delete(id);
  }
  const missedAt = missCache.get(id);
  if (missedAt !== undefined && Date.now() - missedAt < MISS_TTL_MS) return null;
  let entries: fsSync.Dirent[];
  try {
    entries = fsSync.readdirSync(root, { withFileTypes: true });
  } catch {
    missCache.set(id, Date.now());
    return null;
  }
  // Sorted, first claim of an id wins, so two folders carrying the same doc id
  // (a Finder duplicate) resolve deterministically; readProjectEntries gives
  // the twin its own id on the next listing.
  const seen = new Set<string>();
  for (const e of entries.sort((a, b) => a.name.localeCompare(b.name))) {
    if (!e.isDirectory()) continue;
    const doc = readDocSyncAt(path.join(root, e.name));
    if (!doc || typeof doc.id !== "string" || seen.has(doc.id)) continue;
    seen.add(doc.id);
    setDirIndex(doc.id, e.name);
  }
  const found = dirIndex.get(id)?.name ?? null;
  if (!found) missCache.set(id, Date.now());
  return found;
}

// jobs.ts registers the exports in flight; a folder never moves out from under
// a running ffmpeg render (the job's recorded output path must stay live).
// Registered by the jobs module at load; until then nothing renders, so
// nothing blocks.
let hasActiveJobs: (projectId: string) => boolean = () => false;
export function setActiveJobGuard(fn: (projectId: string) => boolean) {
  hasActiveJobs = fn;
}

/** Move the project's folder to match its display name. A conflict takes a
 * numeric suffix; an active render defers the move to the next save. The
 * target is claimed with mkdir first — POSIX rename replaces an empty
 * destination directory, so moving onto a placeholder we own is atomic, and a
 * concurrent create can never have its just-claimed folder replaced. */
function followName(id: string, name: string) {
  const current = resolveDirName(id);
  if (!current || hasActiveJobs(id)) return;
  const root = projectsRoot();
  // A name with nothing Finder can hold leaves the folder where it is.
  const want = dirNameFrom(name, current);
  if (want.toLowerCase() === current.toLowerCase()) {
    if (want === current) return;
    // Case-only rename: same folder on a case-insensitive disk, so there is
    // nothing to claim — rename it in place.
    try {
      fsSync.renameSync(path.join(root, current), path.join(root, want));
      setDirIndex(id, want);
    } catch {
      dirIndex.delete(id);
    }
    return;
  }
  for (let n = 1; ; n++) {
    const candidate = n === 1 ? want : `${want} ${n}`;
    if (isReservedDirName(candidate)) continue;
    // Already parked at this suffix (e.g. "Untitled 2" while "Untitled" is
    // taken): nothing to do.
    if (candidate.toLowerCase() === current.toLowerCase()) return;
    try {
      fsSync.mkdirSync(path.join(root, candidate));
    } catch (err) {
      if ((err as NodeJS.ErrnoException).code === "EEXIST") continue;
      return;
    }
    try {
      fsSync.renameSync(path.join(root, current), path.join(root, candidate));
      setDirIndex(id, candidate);
    } catch {
      // The move failed; give the placeholder back and retry on a later save.
      try {
        fsSync.rmdirSync(path.join(root, candidate));
      } catch {
        // Leave it; a later claim will suffix past it.
      }
      dirIndex.delete(id);
    }
    return;
  }
}

export function projectDir(id: string) {
  assertLocalRuntime();
  if (!ID_RE.test(id)) throw new Error("Invalid project id.");
  // An unknown id falls back to a folder named by the id: a path that does not
  // exist, so reads fail exactly like a deleted project always has.
  return path.join(projectsRoot(), resolveDirName(id) ?? id);
}

/** Startup alignment, run by both mounts before data routes: stamp docs from
 * before stored ids (their folder name was the id) and move every folder to
 * match its display name. Running at every launch makes it one mechanism for
 * the one-time move off id-named folders, for suffixed folders reclaiming a
 * freed name, and for folders renamed in Finder while the engine was away. */
export function reconcileProjectDirs(): void {
  const root = projectsRoot();
  let entries: fsSync.Dirent[];
  try {
    entries = fsSync.readdirSync(root, { withFileTypes: true });
  } catch {
    return;
  }
  for (const e of entries) {
    if (!e.isDirectory()) continue;
    const doc = readDocSyncAt(path.join(root, e.name));
    if (!doc) continue;
    if (typeof doc.id !== "string" || !ID_RE.test(doc.id)) {
      if (!ID_RE.test(e.name)) continue;
      doc.id = e.name;
      try {
        // Atomic with a .bak mirror, like every other doc write — a plain
        // overwrite would leave the .bak holding an id-less doc that a later
        // corruption recovery restores.
        writeDocSync(path.join(root, e.name, "project.json"), doc);
      } catch {
        continue;
      }
    }
    setDirIndex(doc.id, e.name);
    followName(doc.id, typeof doc.name === "string" ? doc.name : "");
  }
}

export const mediaDir = (id: string) => path.join(projectDir(id), "media");
export const exportsDir = (id: string) => path.join(projectDir(id), "exports");
/** A low-res proxy of the actual edit, played on the project card's hover. */
export const previewPath = (id: string) => path.join(projectDir(id), "preview.mp4");

export function mediaPath(id: string, fileName: string) {
  const safe = path.basename(fileName);
  if (!safe || safe.startsWith(".")) throw new Error("Invalid file name.");
  return path.join(mediaDir(id), safe);
}

export function exportPath(id: string, fileName: string) {
  const safe = path.basename(fileName);
  if (!safe || safe.startsWith(".")) throw new Error("Invalid file name.");
  return path.join(exportsDir(id), safe);
}

/** Rendered exports in the project folder, newest first. */
export async function listExports(id: string) {
  const dir = exportsDir(id);
  const names = await readdir(dir).catch(() => [] as string[]);
  const items = await Promise.all(
    names
      .filter((n) => isDeliveryName(n))
      .map(async (n) => {
        const info = await stat(path.join(dir, n)).catch(() => null);
        return info?.isFile() && info.size > 0
          ? { file: n, size: info.size, mtime: info.mtimeMs }
          : null;
      })
  );
  return items
    .filter((x): x is { file: string; size: number; mtime: number } => x !== null)
    .sort((a, b) => b.mtime - a.mtime);
}

/** Remove one rendered export from the project folder. */
export async function deleteExport(id: string, fileName: string) {
  await rm(exportPath(id, fileName), { force: true });
}

/** Remove one media file from the project folder — a media file dies with the
 * last asset that referenced it, so deleted assets don't pile up on disk. */
export async function deleteMedia(id: string, fileName: string) {
  await rm(mediaPath(id, fileName), { force: true });
}

const ORPHAN_MAX_AGE_MS = 24 * 60 * 60 * 1000;

/** Delete media files the doc doesn't reference. Everything under media/ is
 * written to become a doc asset, so an unreferenced file landed for a client
 * that never adopted it — a chat import finishing after the page closed. A day
 * of mtime grace keeps anything a live client might still register. */
export async function sweepOrphanMedia(id: string, doc: ProjectDoc): Promise<void> {
  const dir = mediaDir(id);
  const names = await readdir(dir).catch(() => [] as string[]);
  const referenced = new Set(doc.assets.flatMap((a) => (a.proxy ? [a.fileName, a.proxy.fileName] : [a.fileName])));
  const cutoff = Date.now() - ORPHAN_MAX_AGE_MS;
  for (const name of names) {
    if (referenced.has(name) || name.startsWith(".")) continue;
    const p = path.join(dir, name);
    const info = await stat(p).catch(() => null);
    if (info?.isFile() && info.mtimeMs < cutoff) await rm(p, { force: true });
  }
}

const docPath = (id: string) => path.join(projectDir(id), "project.json");

/** Filesystem metadata makes unchanged-document polls independent of project size. */
export async function projectFileRevision(id: string): Promise<string | null> {
  const info = await stat(docPath(id)).catch(() => null);
  return info ? String(info.mtimeMs) : null;
}

export async function readProject(id: string): Promise<ProjectDoc | null> {
  const file = docPath(id);
  let raw: string;
  try {
    raw = await readFile(file, "utf8");
  } catch {
    return null;
  }
  try {
    return JSON.parse(raw) as ProjectDoc;
  } catch (err) {
    console.error(`Corrupt project doc ${file}:`, err);
  }
  try {
    const doc = JSON.parse(await readFile(`${file}.bak`, "utf8")) as ProjectDoc;
    // The id resolved this folder, so it belongs on the restored doc — a .bak
    // from before ids were stored must not resurrect an id-less doc that the
    // project listing would drop.
    doc.id = id;
    await writeJsonAtomic(file, doc);
    return doc;
  } catch (err) {
    console.error(`Could not recover ${file} from backup:`, err);
    return null;
  }
}

export async function writeProject(id: string, doc: ProjectDoc) {
  doc.id = id;
  doc.updatedAt = Date.now();
  const revision = await writeJsonAtomic(docPath(id), doc);
  followName(id, doc.name);
  return revision;
}

export async function createProject(
  name: string,
  folderId: string | null = null,
  aspect: Aspect | null = null,
  locale: Locale = DEFAULT_LOCALE
): Promise<ProjectSummary> {
  const id = crypto.randomUUID().slice(0, 10);
  const names = await defaultNames(locale);
  const displayName = name.trim() || names.untitled;
  const dirName = await claimDir(dirNameFrom(displayName, names.untitled));
  const dir = path.join(projectsRoot(), dirName);
  await mkdir(path.join(dir, "media"), { recursive: true });
  await mkdir(path.join(dir, "exports"), { recursive: true });
  setDirIndex(id, dirName);
  const now = Date.now();
  // A folder that no longer exists just falls back to the root.
  const folder =
    folderId && (await readFolders()).some((f) => f.id === folderId) ? folderId : null;
  const doc: ProjectDoc = {
    version: 1,
    id,
    name: displayName,
    createdAt: now,
    updatedAt: now,
    assets: [],
    clips: [],
    audioClips: [],
    overlays: [],
    ...(aspect ? { aspect } : {}),
    ...(folder ? { folderId: folder } : {}),
  };
  await writeJsonAtomic(path.join(dir, "project.json"), doc);
  return summarize(id, doc);
}

export async function deleteProject(id: string) {
  const dir = projectDir(id);
  const doc = await readProject(id);
  if (!doc) throw new UserError("project_not_found", "Project not found.");
  // Final backstop before an rm -rf: the folder's own doc must carry the id
  // being deleted, so a mis-resolved folder can never be the one removed.
  if (doc.id !== undefined && doc.id !== id) {
    dirIndex.delete(id);
    throw new UserError("project_not_found", "Project not found.");
  }
  await rm(dir, { recursive: true, force: true });
  dirIndex.delete(id);
}

/** Total bytes under a directory (media, exports, proxy, doc). */
async function dirSize(dir: string): Promise<number> {
  const entries = await readdir(dir, { withFileTypes: true }).catch(() => []);
  let total = 0;
  for (const e of entries) {
    const p = path.join(dir, e.name);
    if (e.isDirectory()) total += await dirSize(p);
    else {
      const info = await stat(p).catch(() => null);
      if (info) total += info.size;
    }
  }
  return total;
}

async function summarize(id: string, doc: ProjectDoc): Promise<ProjectSummary> {
  // Track 0 is the cut: layer clips composite over it, so they add nothing to
  // the summary's duration, count, or poster. Legacy docs carry no `track` on
  // clips — those are all track 0.
  const track0 = doc.clips.filter((c) => (c.track ?? 0) === 0);
  const duration = timelineEnd(doc);
  // Preview: the first clip's source video, else any video asset.
  const firstClip = track0[0];
  const firstClipAsset = firstClip
    ? doc.assets.find((a) => a.id === firstClip.assetId)
    : undefined;
  const previewAsset =
    firstClipAsset ?? doc.assets.find((a) => a.type === "video" || a.type === "image");
  // Poster the clip's actual first frame (its trim-in), not the source's 0s.
  const previewStart = firstClipAsset && firstClip ? firstClip.in : 0;
  const [hasPreview, sizeBytes] = await Promise.all([
    exists(previewPath(id)),
    dirSize(projectDir(id)),
  ]);
  return {
    id,
    name: doc.name,
    createdAt: doc.createdAt,
    updatedAt: doc.updatedAt,
    duration,
    clipCount: track0.length,
    assetCount: doc.assets.length,
    previewFile: previewAsset?.fileName,
    previewIsImage: previewAsset?.type === "image",
    previewStart,
    hasPreview,
    aspect: doc.aspect,
    folderId: doc.folderId ?? null,
    sizeBytes,
  };
}

// --- Project folders: named groups that file into each other; each project's
// doc carries its folderId, so grouping travels with the project. ---

async function readFolders(): Promise<ProjectFolder[]> {
  try {
    const raw = JSON.parse(await readFile(foldersIndex(), "utf8")) as { folders?: ProjectFolder[] };
    return Array.isArray(raw.folders) ? raw.folders : [];
  } catch {
    return [];
  }
}

async function writeFolders(folders: ProjectFolder[]) {
  await mkdir(projectsRoot(), { recursive: true });
  await writeJsonAtomic(foldersIndex(), { folders });
}

// Serialize read-modify-write cycles on the folder list, so two folder changes
// in flight at once can't write each other's out. Each mutation reads the
// freshly-written list, applies its change, and writes.
let foldersLock: Promise<unknown> = Promise.resolve();
async function mutateFolders<T>(fn: (idx: { folders: ProjectFolder[] }) => T): Promise<T> {
  const run = foldersLock.then(async () => {
    const idx = { folders: await readFolders() };
    const result = fn(idx);
    await writeFolders(idx.folders);
    return result;
  });
  foldersLock = run.then(
    () => undefined,
    () => undefined
  );
  return run;
}

export async function listProjectFolders(): Promise<ProjectFolder[]> {
  return settleParents(await readFolders()).sort((a, b) => a.createdAt - b.createdAt);
}

export async function createProjectFolder(
  name: string,
  parentId: string | null = null
): Promise<ProjectFolder> {
  const trimmed = name.trim();
  if (!trimmed) throw new UserError("folder_name_required", "Folder name required.");
  const id = crypto.randomUUID().slice(0, 8);
  return mutateFolders(({ folders }) => {
    const folder: ProjectFolder = {
      id,
      name: trimmed.slice(0, 80),
      parentId: resolveParent(folders, id, parentId),
      createdAt: Date.now(),
    };
    folders.push(folder);
    return folder;
  });
}

/** Rename a folder, file it under another (null for the top level), or
 * both; a key left undefined keeps what the folder has. */
export async function updateProjectFolder(
  id: string,
  patch: { name?: string; parentId?: string | null }
): Promise<ProjectFolder> {
  const trimmed = patch.name?.trim();
  if (patch.name !== undefined && !trimmed) throw new UserError("folder_name_required", "Folder name required.");
  return mutateFolders(({ folders }) => {
    const folder = folders.find((f) => f.id === id);
    if (!folder) throw new UserError("folder_not_found", "Folder not found.");
    if (trimmed) folder.name = trimmed.slice(0, 80);
    if (patch.parentId !== undefined) folder.parentId = resolveParent(folders, id, patch.parentId);
    return folder;
  });
}

/** Delete a folder and everything in it: the folders filed under it, however
 * deep, and every project they hold, each the way its own delete goes. The
 * projects go first and the folders last, so a run that stops partway leaves
 * the rest where a retry finds it. */
export async function deleteProjectFolder(id: string) {
  const folders = await readFolders();
  if (!folders.some((f) => f.id === id)) return;
  const tree = new Set(subtreeOf(folders, id));
  for (const { id: projectId, doc } of await readProjectEntries())
    if (doc.folderId && tree.has(doc.folderId)) await deleteProject(projectId);
  await mutateFolders((idx) => {
    idx.folders = idx.folders.filter((f) => !tree.has(f.id));
  });
}

export async function moveProjectToFolder(id: string, folderId: string | null) {
  const doc = await readProject(id);
  if (!doc) throw new UserError("project_not_found", "Project not found.");
  if (folderId && !(await readFolders()).some((f) => f.id === folderId)) {
    throw new UserError("folder_not_found", "Folder not found.");
  }
  doc.folderId = folderId;
  await writeProject(id, doc);
}

/** Duplicate a project: copy the doc and its media (not its exports) into a
 * fresh project folder. */
export async function duplicateProject(id: string, locale: Locale = DEFAULT_LOCALE): Promise<ProjectSummary> {
  const doc = await readProject(id);
  if (!doc) throw new UserError("project_not_found", "Project not found.");
  const newId = crypto.randomUUID().slice(0, 10);
  const names = await defaultNames(locale);
  const name = names.copy(doc.name);
  const dirName = await claimDir(dirNameFrom(name, names.untitled));
  const dir = path.join(projectsRoot(), dirName);
  await mkdir(path.join(dir, "media"), { recursive: true });
  await mkdir(path.join(dir, "exports"), { recursive: true });
  setDirIndex(newId, dirName);
  await cp(mediaDir(id), path.join(dir, "media"), { recursive: true }).catch(() => {});
  const now = Date.now();
  const copy: ProjectDoc = { ...doc, id: newId, name, createdAt: now, updatedAt: now };
  await writeJsonAtomic(path.join(dir, "project.json"), copy);
  return summarize(newId, copy);
}

/** A folder's doc for listing: project.json, then the .bak mirror (the
 * restore itself happens when readProject opens it). */
async function readDocAt(dirName: string): Promise<ProjectDoc | null> {
  const base = path.join(projectsRoot(), dirName);
  for (const file of ["project.json", "project.json.bak"]) {
    try {
      return JSON.parse(await readFile(path.join(base, file), "utf8")) as ProjectDoc;
    } catch {
      // Missing or unreadable; try the mirror.
    }
  }
  return null;
}

/** Every project on disk: read each folder's doc concurrently — listing
 * latency shouldn't grow linearly with the number of projects. The scan
 * refreshes the id index, and it repairs duplicate ids: when two folders
 * carry the same doc id (a project duplicated in Finder), the one the index
 * already points at keeps the id — else the most recently edited — and each
 * twin is stamped with a fresh id of its own, making it the independent copy
 * the duplication was after. */
async function readProjectEntries(): Promise<{ id: string; doc: ProjectDoc }[]> {
  assertLocalRuntime();
  await mkdir(projectsRoot(), { recursive: true });
  const entries = await readdir(projectsRoot(), { withFileTypes: true });
  const dirs = entries
    .filter((e) => e.isDirectory())
    .map((e) => e.name)
    .sort((a, b) => a.localeCompare(b));
  const found = (
    await Promise.all(
      dirs.map(async (dirName) => {
        const doc = await readDocAt(dirName);
        if (!doc || typeof doc.id !== "string" || !ID_RE.test(doc.id)) return null;
        return { dirName, doc };
      })
    )
  ).filter((x): x is { dirName: string; doc: ProjectDoc } => x !== null);

  const byId = new Map<string, { dirName: string; doc: ProjectDoc }[]>();
  for (const entry of found) {
    const group = byId.get(entry.doc.id!) ?? [];
    group.push(entry);
    byId.set(entry.doc.id!, group);
  }

  const result: { id: string; doc: ProjectDoc }[] = [];
  for (const [id, group] of byId) {
    const indexed = dirIndex.get(id)?.name;
    const keeper =
      group.find((g) => g.dirName === indexed) ??
      group.reduce((a, b) => (b.doc.updatedAt > a.doc.updatedAt ? b : a));
    setDirIndex(id, keeper.dirName);
    result.push({ id, doc: keeper.doc });
    for (const twin of group) {
      if (twin === keeper) continue;
      const freshId = crypto.randomUUID().slice(0, 10);
      twin.doc.id = freshId;
      try {
        await writeJsonAtomic(path.join(projectsRoot(), twin.dirName, "project.json"), twin.doc);
        setDirIndex(freshId, twin.dirName);
        result.push({ id: freshId, doc: twin.doc });
        console.log(`re-identified duplicate project folder "${twin.dirName}" as ${freshId}`);
      } catch {
        // Unwritable twin: leave it off the list; the winner keeps the id.
      }
    }
  }
  return result;
}

export async function listProjects(): Promise<ProjectSummary[]> {
  const found = await readProjectEntries();
  const summaries = await Promise.all(found.map(({ id, doc }) => summarize(id, doc)));
  return summaries.sort((a, b) => b.updatedAt - a.updatedAt);
}

/** Store an uploaded media file in the project folder, deduping the name. */
export async function saveMedia(id: string, file: File): Promise<string> {
  await mkdir(mediaDir(id), { recursive: true });
  const base = path
    .basename(file.name)
    .replace(/[^\w.\-() ]+/g, "_")
    .slice(-80);
  const fileName = await uniqueName(base, (n) => mediaPath(id, n));
  await writeFile(mediaPath(id, fileName), Buffer.from(await file.arrayBuffer()));
  return fileName;
}