feat(studio): media references for imported courses (path, size, sha256, .gitignore)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

packages/feature-studio/src/server/media-refs.ts

@@ -0,0 +1,61 @@
+import { extname } from "node:path";
+import { checkRelPath } from "./relpath";
+
+/**
+ * Large media of a converted import stay out of git (v1.1 S, docs/operations.md "Imported courses in the studio").
+ * The repo commits `MEDIA_REFS` (path, size and checksum per file, spec 5) and a `.gitignore` line per path;
+ * every studio worktree gets the files as hard links to `<dataDir>/media/<courseId>/<path>`.
+ */
+export const MEDIA_REFS = ".stcourses/media.json";
+export const LARGE_FILE_BYTES = 8 * 1024 * 1024;
+const MEDIA_EXT = new Set(["mp4", "m4v", "webm", "mov", "mkv", "avi", "mp3", "m4a", "wav", "ogg", "oga", "opus", "flac"]);
+
+export interface MediaRef { path: string; size: number; sha256: string }
+
+/** Video and audio always; anything else only when it is over `LARGE_FILE_BYTES`. */
+export function isLargeMedia(rel: string, size: number): boolean {
+  return MEDIA_EXT.has(extname(rel).slice(1).toLowerCase()) || size > LARGE_FILE_BYTES;
+}
+
+/** One anchored `.gitignore` pattern matching exactly `rel`. Throws for names a `.gitignore` line cannot hold. */
+export function gitignoreLine(rel: string): string {
+  if (/[\n\r]/.test(rel)) throw new Error(`a file name with a line break cannot be kept out of git: ${JSON.stringify(rel)}`);
+  let s = rel.replace(/[\\*?[\]]/g, (c) => `\\${c}`);
+  const trail = /( +)$/.exec(s)?.[1]?.length ?? 0;
+  if (trail) s = s.slice(0, -trail) + "\\ ".repeat(trail);
+  return `/${s}`;
+}
+
+const HEADER = "# Imported media kept outside git: see .stcourses/media.json (STCourses)";
+
+/** The repo's root `.gitignore`: the course's own one (if any) first, then one line per referenced file. */
+export function mediaGitignore(paths: string[], existing: string | null): string {
+  const own = existing ? (existing.endsWith("\n") ? existing : existing + "\n") + "\n" : "";
+  return `${own}${HEADER}\n${paths.map(gitignoreLine).join("\n")}\n`;
+}
+
+export async function sha256File(abs: string): Promise<string> {
+  const h = new Bun.CryptoHasher("sha256");
+  for await (const chunk of Bun.file(abs).stream()) h.update(chunk);
+  return h.digest("hex");
+}
+
+export function stringifyMediaRefs(files: MediaRef[]): string {
+  return JSON.stringify({ schema: 1, files }, null, 2) + "\n";
+}
+
+/** The reference list, or null when the text is not a valid one (every path must pass `checkRelPath`). */
+export function parseMediaRefs(text: string): MediaRef[] | null {
+  let raw: unknown;
+  try { raw = JSON.parse(text); } catch { return null; }
+  const r = raw as { schema?: unknown; files?: unknown } | null;
+  if (!r || r.schema !== 1 || !Array.isArray(r.files)) return null;
+  const out: MediaRef[] = [];
+  for (const f of r.files as Partial<MediaRef>[]) {
+    if (!f || typeof f.path !== "string" || typeof f.size !== "number" || !Number.isInteger(f.size) || f.size < 0) return null;
+    if (typeof f.sha256 !== "string" || !/^[0-9a-f]{64}$/.test(f.sha256)) return null;
+    try { if (checkRelPath(f.path) !== f.path) return null; } catch { return null; }
+    out.push({ path: f.path, size: f.size, sha256: f.sha256 });
+  }
+  return out;
+}

packages/feature-studio/src/server/relpath.ts

@@ -0,0 +1,12 @@
+import { isAbsolute, normalize, sep } from "node:path";
+
+/** Normalised relative path, or throws. Rejects absolute paths, `..`, `.git` and NUL. */
+export function checkRelPath(p: string): string {
+  if (typeof p !== "string" || p === "" || p.includes("\0") || isAbsolute(p) || p.includes("\\")) throw new Error(`invalid path: ${JSON.stringify(p)}`);
+  const n = normalize(p);
+  const parts = n.split(sep);
+  if (n === "." || parts[0] === ".." || parts.some((x) => x === ".." || x.toLowerCase() === ".git") || n.endsWith(sep)) {
+    throw new Error(`invalid path: ${JSON.stringify(p)}`);
+  }
+  return n;
+}

packages/feature-studio/src/server/store.ts

@@ -1,8 +1,11 @@
 import { constants, existsSync, lstatSync, mkdirSync, readdirSync, realpathSync, rmSync, statSync } from "node:fs";
 import { mkdir, open, rm, unlink } from "node:fs/promises";
-import { dirname, isAbsolute, join, normalize, sep } from "node:path";
+import { dirname, join, sep } from "node:path";
 import { loadCourse, type Diagnostic } from "@stc/course-format";
 import { git, gitOk, splitZ, withLock, type Identity } from "./git";
+import { checkRelPath } from "./relpath";
+
+export { checkRelPath } from "./relpath";
 
 export type { Identity } from "./git";
 
@@ -19,17 +22,6 @@ export function safeAuthor(authorId: string): string {
   return s === "" ? "_" : s;
 }
 
-/** Normalised relative path, or throws. Rejects absolute paths, `..`, `.git` and NUL. */
-export function checkRelPath(p: string): string {
-  if (typeof p !== "string" || p === "" || p.includes("\0") || isAbsolute(p) || p.includes("\\")) throw new Error(`invalid path: ${JSON.stringify(p)}`);
-  const n = normalize(p);
-  const parts = n.split(sep);
-  if (n === "." || parts[0] === ".." || parts.some((x) => x === ".." || x.toLowerCase() === ".git") || n.endsWith(sep)) {
-    throw new Error(`invalid path: ${JSON.stringify(p)}`);
-  }
-  return n;
-}
-
 export interface FileWrite {
   path: string;
   content?: string | Uint8Array;