reelkit-cli 0.1.0

package/src/contract/index.ts

@@ -0,0 +1,157 @@
+// The rules a server of this API must follow. The CLI and the fake API (src/testing/fake-api.ts) rely on every one.
+//
+// - Every route with `auth: true` takes `Authorization: Bearer <token>`.
+// - Errors are `{ "error": { "code", "message" } }` and always use a non-2xx status: 401 unauthenticated, 429 quota_exceeded,
+//   404 not_found, 400 invalid_request, 500 server_error. The client reads `error.code` from the body.
+//   A `quota_exceeded` message says when the limit resets or how long to wait (a date for a monthly quota, "wait a minute" for a throttle).
+// - Pull returns an item only if it is published or belongs to the caller; anything else is not_found.
+//   Commit works only for the user who uploaded the item.
+// - Text sent to the server is bounded and plain: no control characters (C0 other than tab, newline and carriage return, DEL) and no lone surrogates,
+//   within the length of its field; anything else is 400 invalid_request before any paid service is called.
+// - A voiceover `text` has its line endings normalised by the server (`\r\n` and a lone `\r` become `\n`) before it is counted for the quota
+//   and before it is spoken; `chars` in the answer is the normalised length.
+// - A voiceover `text` must contain at least one non-space character: whitespace alone is 400 invalid_request.
+// - A library item `id` (pull, commit) matches `^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$`; a `deviceCode` is 1 to 200 characters of plain text.
+// - A `voiceId` is 1 to 64 letters and digits and must be one of the voices the server lists (`voices`), otherwise 400 invalid_request.
+// - Components are added to the library only by the owner's scripts, never through this API (UploadKindSchema has no `component`).
+// - Upload is a single `PUT` to `uploadUrl` with exactly the declared content type and byte length, and no auth header.
+//   Anything else is refused with a non-2xx status and stores nothing. That refusal comes from the storage service, so its body
+//   is not an API error and a client must not parse it.
+// - A client sends one `PUT` per upload URL, then commits. If the `PUT` fails, is refused or its outcome is unknown, the client starts a new
+//   upload (`libraryUpload`): it may not rely on a URL working a second time. A server may keep an upload URL usable until it expires
+//   (a presigned URL on object storage is), so a second `PUT` can succeed there; the fake API does not allow it.
+// - On every server, whatever is sent to an upload URL, at any time, can never change an object that is being served:
+//   the upload goes to a staging object, and commit moves it to where it is served. Commit succeeds only for an object that was stored
+//   with the declared content type and byte length (the `PUT` enforces the type, commit checks the length); otherwise it is 400 invalid_request.
+// - An upload is a library item only after commit: before that it is not found by pull (`not_found`) or search, even for its uploader.
+//   Committing the same item again returns the same item and counts as one contribution.
+// - Upload rules, all `invalid_request`: the content type must fit the kind (image: `image/*`; clip and overlay: `video/*`; sfx and music:
+//   `audio/*`) and `bytes` is from 1 to 209,715,200 (200 MB). A server may rewrite the file name to a safe one (every character outside
+//   `A-Za-z0-9._-` becomes `_`); a name that then does not start with a letter or digit, or is longer than 128 characters, is refused.
+//   `pull` returns the server's file name, which may differ from the one uploaded.
+// - Ordering: search results are ordered by `match`, highest first: a number from 0 to 1 (the server rounds it to two decimals), the probability
+//   that the item is good enough to reuse for the query. A server finds candidates by meaning and may judge them with a model, so `match` is not
+//   a share of words; the order of results with the same `match` is not specified. The public listing is newest first; with a query it is best
+//   match first, equal matches newest first. Paging continues the same order, with no item twice. `page` is from 1 to 10000.
+// - A server may add tags (and a description when the uploader gave none) to an item that is shared, after upload or generation; the tags the
+//   uploader gave stay in it, first.
+// - Upload URLs and file URLs must be unguessable (random or signed; never derived from an item id or a counter) and scoped to one object:
+//   a file URL serves one file, an upload URL accepts uploads for one object only.
+// - The public listing's `previewUrl` is a preview that needs no login. An item with a preview of its own gets that one; otherwise an `image`
+//   or an `sfx` gets a URL of its own file (a picture and a short sound need no login to look at or hear), and every other kind (music,
+//   overlay, clip, component), whose full file is long media or code, gets no `previewUrl`.
+// - Every returned URL needs no headers and stays valid for at least five minutes.
+// - The generation routes (`voiceover`, `images`) are synchronous: they return the URL of the finished file.
+// - `durationSec` is the decoded audio length; `words` are in seconds from the start of that audio.
+// - Search returns published items only, and leaves out items that are not matches at all; the default `limit` is 8.
+import { z } from "zod";
+import { AspectSchema, WordTimingSchema } from "../pipeline/schema";
+
+// Text that is safe to store and to pass to a provider: at most `max` characters, no control characters (C0 except tab, newline and
+// carriage return, DEL)
+// and no lone surrogates.
+const CONTROL = /[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F]/;
+const LONE_SURROGATE = /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/;
+export const isPlainText = (s: string): boolean => !CONTROL.test(s) && !LONE_SURROGATE.test(s);
+export const text = (max: number) => z.string().max(max).refine(isPlainText, "must be plain text without control characters");
+
+// A library item id: letters and digits first, then letters, digits, dot, underscore and dash; at most 128 characters.
+const ItemId = z.string().regex(/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/);
+
+const MAX_META_BYTES = 4000;
+const plainValues = (v: unknown, depth = 0): boolean => {
+  if (typeof v === "string") return isPlainText(v);
+  if (depth > 20) return false;
+  if (Array.isArray(v)) return v.every((x) => plainValues(x, depth + 1));
+  if (v && typeof v === "object") return Object.entries(v).every(([k, x]) => isPlainText(k) && plainValues(x, depth + 1));
+  return true;
+};
+const Meta = z.record(z.string(), z.unknown()).refine((m) => new TextEncoder().encode(JSON.stringify(m)).length <= MAX_META_BYTES, `must be at most ${MAX_META_BYTES} bytes`)
+  .refine((m) => plainValues(m), "must not contain control characters");
+
+// The most a single upload may be: 200 MB.
+export const MAX_UPLOAD_BYTES = 209_715_200;
+
+export const ErrorCodeSchema = z.enum(["unauthenticated", "quota_exceeded", "not_found", "invalid_request", "server_error"]);
+export type ErrorCode = z.infer<typeof ErrorCodeSchema>;
+// The code is any string here: a code this version does not know still carries a message worth showing (the client maps it to server_error).
+export const ApiErrorSchema = z.object({ error: z.object({ code: z.string(), message: z.string() }) });
+
+export const LibraryKindSchema = z.enum(["image", "overlay", "sfx", "music", "component", "clip"]);
+export type LibraryKind = z.infer<typeof LibraryKindSchema>;
+// What a user may upload: everything except components, which are code and come only from Reelkit.
+export const UploadKindSchema = LibraryKindSchema.exclude(["component"]);
+export type UploadKind = z.infer<typeof UploadKindSchema>;
+
+export const LibraryItemSchema = z.object({
+  id: z.string(),
+  kind: LibraryKindSchema,
+  title: z.string(),
+  description: z.string(),
+  tags: z.array(z.string()),
+  // width, height, durationSec, aspect, props, source, licence: whatever applies to the kind.
+  meta: z.record(z.string(), z.unknown()),
+  visibility: z.enum(["private", "review", "published"]),
+});
+export type LibraryItem = z.infer<typeof LibraryItemSchema>;
+
+export const VoiceSchema = z.object({
+  id: z.string(), name: z.string(), description: z.string(),
+  gender: z.string().optional(), accent: z.string().optional(), language: z.string().optional(), useCase: z.string().optional(),
+  kind: z.enum(["stock", "cloned", "designed"]),
+});
+export type Voice = z.infer<typeof VoiceSchema>;
+
+const Meter = z.object({ used: z.number(), limit: z.number() });
+export const MeSchema = z.object({
+  userId: z.string(), handle: z.string(),
+  quota: z.object({ voiceoverChars: Meter, images: Meter, resetsAt: z.string() }),
+  contributions: z.number(),
+});
+
+const Empty = z.object({});
+const route = <Q extends z.ZodType, S extends z.ZodType>(method: "GET" | "POST", path: string, auth: boolean, req: Q, res: S) => ({ method, path, auth, req, res });
+
+export const routes = {
+  deviceStart: route("POST", "/auth/device", false,
+    z.object({ label: text(80) }),
+    z.object({ deviceCode: z.string(), userCode: z.string(), verificationUrl: z.string(), intervalSec: z.number().min(1), expiresInSec: z.number().positive() })),
+  deviceToken: route("POST", "/auth/token", false,
+    z.object({ deviceCode: text(200).min(1) }),
+    z.discriminatedUnion("status", [
+      z.object({ status: z.literal("pending") }),
+      z.object({ status: z.literal("expired") }),
+      z.object({ status: z.literal("approved"), token: z.string() }),
+    ])),
+  revoke: route("POST", "/auth/revoke", true, Empty, z.object({ revoked: z.boolean() })),
+  me: route("GET", "/me", true, Empty, MeSchema),
+  librarySearch: route("GET", "/library/search", true,
+    z.object({ q: text(200).min(1), kind: LibraryKindSchema.optional(), limit: z.coerce.number().int().min(1).max(50).optional() }),
+    z.object({ items: z.array(LibraryItemSchema.extend({ match: z.number().min(0).max(1) })) })),
+  libraryPull: route("POST", "/library/pull", true,
+    z.object({ id: ItemId }),
+    z.object({ item: LibraryItemSchema, url: z.string(), filename: z.string().regex(/^[A-Za-z0-9][A-Za-z0-9._-]*$/) })),
+  libraryUpload: route("POST", "/library/upload", true,
+    z.object({
+      kind: UploadKindSchema, title: text(200).min(1), description: text(2000), tags: z.array(text(40)).max(20),
+      meta: Meta, filename: text(200).min(1), contentType: text(100), bytes: z.number().int().positive().max(MAX_UPLOAD_BYTES),
+      shareable: z.boolean(),
+    }),
+    z.object({ id: z.string(), uploadUrl: z.string() })),
+  libraryCommit: route("POST", "/library/upload/commit", true, z.object({ id: ItemId }), z.object({ item: LibraryItemSchema })),
+  voices: route("GET", "/voices", true, Empty, z.object({ voices: z.array(VoiceSchema) })),
+  voiceover: route("POST", "/voiceover", true,
+    z.object({ text: text(5000).refine((t) => /\S/.test(t), "must contain a non-space character"), voiceId: z.string().regex(/^[A-Za-z0-9]{1,64}$/).optional(), speed: z.number().min(0.7).max(1.3).optional() }),
+    z.object({ url: z.string(), ext: z.enum(["mp3", "wav", "m4a"]), contentType: z.string(), durationSec: z.number().positive(), words: z.array(WordTimingSchema), chars: z.number() })),
+  images: route("POST", "/images", true,
+    z.object({ prompt: text(2000).min(1), aspect: AspectSchema, shareable: z.boolean(), tags: z.array(text(40)).max(12) }),
+    // libraryId is set when the image was also added to the shared library.
+    z.object({ url: z.string(), ext: z.enum(["png", "jpg", "jpeg", "webp"]), contentType: z.string(), libraryId: z.string().optional() })),
+  publicLibrary: route("GET", "/public/library", false,
+    z.object({ q: text(200).optional(), kind: LibraryKindSchema.optional(), page: z.coerce.number().int().min(1).max(10000).optional() }),
+    // With `q` the items are the best matches by meaning, best first, each with `match` (0..1), in one page (`hasMore` false). Under heavy
+    // use, or when ranking fails, the server answers the plain text listing instead (no `match`), so a client must accept both.
+    z.object({ items: z.array(LibraryItemSchema.extend({ previewUrl: z.string().optional(), match: z.number().min(0).max(1).optional() })), page: z.number(), hasMore: z.boolean() })),
+};
+export type Routes = typeof routes;
+export type RouteName = keyof Routes;

package/src/credentials.ts

@@ -0,0 +1,55 @@
+import { chmodSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+type Env = Record<string, string | undefined>;
+export const DEFAULT_API_URL = "https://reelkit-kohl.vercel.app/api/v1";
+
+export const configDir = (env: Env) => env.REELKIT_CONFIG_DIR || join(homedir(), ".config", "reelkit");
+export const credentialsPath = (env: Env) => join(configDir(env), "credentials.json");
+
+export function loadCredentials(env: Env): { token: string } | undefined {
+  // A file that cannot be read or parsed counts as not logged in, so logging in again can replace it.
+  try {
+    const parsed = JSON.parse(readFileSync(credentialsPath(env), "utf8")) as { token?: unknown } | null;
+    return typeof parsed?.token === "string" && parsed.token ? { token: parsed.token } : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+export function saveCredentials(env: Env, creds: { token: string }): void {
+  mkdirSync(configDir(env), { recursive: true, mode: 0o700 });
+  writeFileSync(credentialsPath(env), JSON.stringify(creds, null, 2), { mode: 0o600 });
+  // writeFileSync only applies the mode when it creates the file.
+  chmodSync(credentialsPath(env), 0o600);
+}
+
+export function clearCredentials(env: Env): void {
+  rmSync(credentialsPath(env), { force: true });
+}
+
+// A login started with `auth login --start` and not yet finished.
+export type PendingLogin = { deviceCode: string; userCode: string; verificationUrl: string; intervalSec: number; expiresAt: number };
+export const pendingLoginPath = (env: Env) => join(configDir(env), "pending-login.json");
+
+export function loadPendingLogin(env: Env): PendingLogin | undefined {
+  try {
+    const p = JSON.parse(readFileSync(pendingLoginPath(env), "utf8")) as Partial<PendingLogin>;
+    if (!p.deviceCode || typeof p.expiresAt !== "number") return undefined;
+    // A file from before the interval was kept, or a damaged one, polls once a second.
+    return { ...(p as PendingLogin), intervalSec: typeof p.intervalSec === "number" && Number.isFinite(p.intervalSec) ? p.intervalSec : 1 };
+  } catch {
+    return undefined;
+  }
+}
+
+export function savePendingLogin(env: Env, pending: PendingLogin): void {
+  mkdirSync(configDir(env), { recursive: true, mode: 0o700 });
+  writeFileSync(pendingLoginPath(env), JSON.stringify(pending, null, 2), { mode: 0o600 });
+  chmodSync(pendingLoginPath(env), 0o600);
+}
+
+export function clearPendingLogin(env: Env): void {
+  rmSync(pendingLoginPath(env), { force: true });
+}

package/src/open.ts

@@ -0,0 +1,48 @@
+import { spawn as nodeSpawn } from "node:child_process";
+
+// The part of child_process.spawn this module uses, so a test can pass a recorder and never start a process.
+export type SpawnFn = (cmd: string, args: string[], opts: { detached: true; stdio: "ignore"; windowsHide?: true }) => { unref(): void; on(event: "error", listener: (e: Error) => void): unknown };
+
+// What starts the default browser on each platform. The URL is one argument, never part of a command string, and never goes through a shell.
+// Windows uses rundll32 rather than `cmd /c start`: cmd expands %NAME% in its command line, which would put the person's environment
+// variables into an address the server chose.
+export function openCommand(url: string, platform: NodeJS.Platform): { cmd: string; args: string[] } {
+  if (platform === "darwin") return { cmd: "open", args: [url] };
+  if (platform === "win32") return { cmd: "rundll32", args: ["url.dll,FileProtocolHandler", url] };
+  return { cmd: "xdg-open", args: [url] };
+}
+
+const isLoopback = (host: string) => host === "localhost" || host === "127.0.0.1" || host === "[::1]" || host.endsWith(".localhost");
+
+// The normalised address if it is safe to hand to a browser launcher, otherwise null. The address may come from a server, so: https (http
+// only for this machine), no credentials, no control characters, and no `%` that is not a valid percent-encoding.
+export function openableUrl(url: string): string | null {
+  // eslint-disable-next-line no-control-regex
+  const control = /[\u0000-\u001f\u007f]/;
+  if (control.test(url)) return null;
+  let u: URL;
+  try { u = new URL(url); } catch { return null; }
+  if (u.protocol !== "http:" && u.protocol !== "https:") return null;
+  if (u.username || u.password) return null;
+  if (u.protocol === "http:" && !isLoopback(u.hostname)) return null;
+  if (control.test(u.href) || /%(?![0-9a-fA-F]{2})/.test(u.href)) return null;
+  return u.href;
+}
+
+// Opens a web page in the person's browser. Resolves true if it tried to open it and false if it refused (the address is not one that is
+// safe to open, see openableUrl). A refusal is not an error, and neither is a missing command (a server, a container, no desktop): the
+// caller has already printed the address, so the person can open it themselves.
+export async function openInBrowser(url: string, opts: { platform?: NodeJS.Platform; spawn?: SpawnFn } = {}): Promise<boolean> {
+  const href = openableUrl(url);
+  if (href === null) return false;
+  const platform = opts.platform ?? process.platform;
+  const { cmd, args } = openCommand(href, platform);
+  const spawn = opts.spawn ?? (nodeSpawn as unknown as SpawnFn);
+  try {
+    const child = spawn(cmd, args, platform === "win32" ? { detached: true, stdio: "ignore", windowsHide: true } : { detached: true, stdio: "ignore" });
+    // A missing command is reported later as an error event; handled, it is not a crash.
+    child.on("error", () => undefined);
+    child.unref();
+  } catch { /* the same: nothing to open it with */ }
+  return true;
+}

package/src/pipeline/review.ts

@@ -0,0 +1,30 @@
+import { WORDS_PER_SEC, type AssetRecord, type ScenePlan } from "./schema";
+
+const words = (s: string) => s.trim().split(/\s+/).filter(Boolean).length;
+
+// Soft quality checks on a plan that already passes the hard rules in validatePlan.
+// These are things worth improving in the script; they never fail a video on their own.
+export function reviewPlan(plan: ScenePlan, ctx: { footage?: AssetRecord }): string[] {
+  const issues: string[] = [];
+  const total = plan.scenes.reduce((n, s) => n + words(s.narration), 0);
+  const seconds = total / WORDS_PER_SEC;
+
+  if (!ctx.footage) {
+    if (seconds < 20) issues.push(`The script runs about ${seconds.toFixed(0)}s (${total} words). Aim for 30 to 60 seconds.`);
+    if (seconds > 70) issues.push(`The script runs about ${seconds.toFixed(0)}s (${total} words). Cut it to 60 seconds or less.`);
+    const illustrations = plan.scenes.filter((s) => s.treatment === "illustration").length;
+    if (illustrations > Math.ceil(plan.scenes.length / 2))
+      issues.push(`${illustrations} of ${plan.scenes.length} scenes are illustrations. Use illustrations for at most half the scenes.`);
+  }
+
+  if (words(plan.scenes[0].narration) > 30) issues.push(`The hook (scene ${plan.scenes[0].id}) is ${words(plan.scenes[0].narration)} words. Keep the first scene under 30 words.`);
+
+  for (const s of plan.scenes) {
+    const n = words(s.narration);
+    if (!ctx.footage && n < 5) issues.push(`Scene ${s.id} has only ${n} words of narration; give it one full sentence.`);
+    if (n > 45) issues.push(`Scene ${s.id} has ${n} words of narration; split it or cut it to under 45.`);
+    if (s.onScreenText.length > 3) issues.push(`Scene ${s.id} has ${s.onScreenText.length} on-screen text items; use at most 3.`);
+    for (const t of s.onScreenText) if (words(t) > 7) issues.push(`Scene ${s.id}: on-screen text "${t}" is too long; keep each item to 7 words or fewer.`);
+  }
+  return issues;
+}

package/src/pipeline/schema.ts

@@ -0,0 +1,110 @@
+import { z } from "zod";
+
+export const WORDS_PER_SEC = 2.5;
+
+export const AspectSchema = z.enum(["9:16", "16:9", "1:1"]);
+export type Aspect = z.infer<typeof AspectSchema>;
+
+export const SceneSchema = z.object({
+  id: z.string().regex(/^[a-z0-9-]+$/).describe("short unique id, lowercase letters, digits, dashes"),
+  narration: z.string().min(1).describe("the words spoken in this scene"),
+  treatment: z.enum(["motion-graphic", "illustration", "footage-overlay"]),
+  onScreenText: z.array(z.string()),
+  imagePrompt: z.string().nullable().describe("required when treatment is illustration, otherwise null"),
+  shareable: z.boolean().describe("true only when imagePrompt is fully generic: no brand, product, person or detail specific to this user. Such images are saved to a library shared by all users."),
+  imageTags: z.array(z.string()).describe("3 to 6 short tags describing the illustration; empty when imagePrompt is null"),
+  userAssetIds: z.array(z.string()),
+  notes: z.string().describe("visual direction for whoever writes the composition"),
+});
+export type Scene = z.infer<typeof SceneSchema>;
+
+export const ScenePlanSchema = z.object({
+  title: z.string(),
+  aspect: AspectSchema,
+  mode: z.enum(["motion", "footage"]),
+  // Optional only so plans stored before voices existed still load; a new plan must choose one.
+  voiceId: z.string().optional().describe("id of the narration voice, one of the ids from `reelkit assets voices`, chosen to suit the idea, audience and language"),
+  pace: z.enum(["slow", "normal", "fast"]).optional().describe("speaking pace: slow for calm or emotional, normal by default, fast for high-energy"),
+  scenes: z.array(SceneSchema).min(3).max(8),
+});
+
+export const PACE_SPEED = { slow: 0.92, normal: 1, fast: 1.1 } as const;
+export type ScenePlan = z.infer<typeof ScenePlanSchema>;
+
+export const AssetRecordSchema = z.object({
+  id: z.string(),
+  filename: z.string(),
+  key: z.string(),
+  kind: z.enum(["video", "image", "audio"]),
+  contentType: z.string(),
+  bytes: z.number(),
+  width: z.number().optional(),
+  height: z.number().optional(),
+  durationSec: z.number().optional(),
+  // What the file shows, as given at upload, so the plan can place it where it is relevant.
+  description: z.string().optional(),
+  createdAt: z.string(),
+});
+export type AssetRecord = z.infer<typeof AssetRecordSchema>;
+
+export const WordTimingSchema = z.object({ word: z.string(), startSec: z.number(), endSec: z.number() });
+export type WordTiming = z.infer<typeof WordTimingSchema>;
+
+export const ManifestSceneSchema = z.object({
+  id: z.string(),
+  startFrame: z.number(),
+  durationFrames: z.number(),
+  voiceoverKey: z.string().optional(),
+  words: z.array(WordTimingSchema),
+  imageKey: z.string().optional(),
+  userAssetKeys: z.array(z.string()),
+});
+export type ManifestScene = z.infer<typeof ManifestSceneSchema>;
+
+export const AssetManifestSchema = z.object({
+  fps: z.number(),
+  width: z.number(),
+  height: z.number(),
+  totalFrames: z.number(),
+  footageKey: z.string().optional(),
+  scenes: z.array(ManifestSceneSchema),
+});
+export type AssetManifest = z.infer<typeof AssetManifestSchema>;
+
+const wordCount = (s: string) => s.trim().split(/\s+/).filter(Boolean).length;
+
+export function validatePlan(
+  plan: ScenePlan,
+  ctx: { aspect: Aspect; footage?: AssetRecord; assets: AssetRecord[]; voiceIds?: string[] },
+): string[] {
+  const errors: string[] = [];
+  if (ctx.voiceIds) {
+    if (!plan.voiceId) errors.push("Choose a narration voice: set voiceId to one of the ids from `reelkit assets voices`.");
+    else if (!ctx.voiceIds.includes(plan.voiceId)) errors.push(`voiceId ${plan.voiceId} is not one of the available voices.`);
+  }
+  const ids = plan.scenes.map((s) => s.id);
+  if (new Set(ids).size !== ids.length) errors.push("Duplicate scene ids.");
+
+  if (ctx.footage) {
+    if (plan.mode !== "footage") errors.push('mode must be "footage" because footage was provided.');
+    if (plan.scenes.some((s) => s.treatment !== "footage-overlay"))
+      errors.push('Every scene must use treatment "footage-overlay" in footage mode.');
+    const budget = Math.floor((ctx.footage.durationSec ?? 0) * WORDS_PER_SEC);
+    const total = plan.scenes.reduce((n, s) => n + wordCount(s.narration), 0);
+    if (total > budget) errors.push(`Narration is ${total} words; the footage allows at most ${budget} words.`);
+  } else {
+    if (plan.mode !== "motion") errors.push('mode must be "motion" because no footage was provided.');
+    if (plan.scenes.some((s) => s.treatment === "footage-overlay"))
+      errors.push('treatment "footage-overlay" is not allowed without footage.');
+    if (plan.aspect !== ctx.aspect) errors.push(`aspect must be ${ctx.aspect}.`);
+  }
+
+  const allowed = new Set(ctx.assets.map((a) => a.id));
+  for (const s of plan.scenes) {
+    if (s.treatment === "illustration" && !s.imagePrompt)
+      errors.push(`Scene ${s.id}: imagePrompt is required for an illustration.`);
+    for (const id of s.userAssetIds)
+      if (!allowed.has(id)) errors.push(`Scene ${s.id}: unknown user asset ${id}.`);
+  }
+  return errors;
+}

package/src/pipeline/timing.ts

@@ -0,0 +1,30 @@
+import type { Aspect, AssetRecord } from "./schema";
+
+export const FPS = 30;
+export const SCENE_PADDING_SEC = 0.4;
+
+export const secondsToFrames = (sec: number, fps = FPS) => Math.ceil(sec * fps - 1e-9);
+
+// padSec is the breathing room after each scene's narration.
+export function layoutScenes(durationsSec: number[], fps = FPS, padSec = SCENE_PADDING_SEC) {
+  let cursor = 0;
+  const scenes = durationsSec.map((d) => {
+    const durationFrames = secondsToFrames(d + padSec, fps);
+    const scene = { startFrame: cursor, durationFrames };
+    cursor += durationFrames;
+    return scene;
+  });
+  return { scenes, totalFrames: cursor };
+}
+
+const even = (n: number) => Math.max(2, Math.floor(n / 2) * 2);
+
+export function dimensionsFor(aspect: Aspect, footage?: AssetRecord) {
+  if (footage?.width && footage?.height) {
+    const scale = Math.min(1, 1920 / Math.max(footage.width, footage.height));
+    return { width: even(footage.width * scale), height: even(footage.height * scale) };
+  }
+  if (aspect === "16:9") return { width: 1920, height: 1080 };
+  if (aspect === "1:1") return { width: 1080, height: 1080 };
+  return { width: 1080, height: 1920 };
+}

package/src/project/manifest.ts

@@ -0,0 +1,71 @@
+import { PACE_SPEED, type AssetManifest, type ScenePlan, type WordTiming } from "../pipeline/schema";
+import { dimensionsFor, FPS, layoutScenes } from "../pipeline/timing";
+import { FILES, type Project } from "./project";
+
+// What a scene was recorded from is stored with it, so a changed script or voice is noticed.
+export type Voiceover = { key: string; durationSec: number; words: WordTiming[]; text?: string; voiceId?: string; speed?: number };
+
+// True when the stored recording no longer matches what the plan asks for. An entry from before this was tracked counts as different.
+export function voiceoverStale(vo: Voiceover, scene: ScenePlan["scenes"][number], plan: ScenePlan): boolean {
+  return vo.text !== scene.narration || vo.voiceId !== plan.voiceId || vo.speed !== PACE_SPEED[plan.pace ?? "normal"];
+}
+
+// Lays the scenes out on the timeline from the real voiceover lengths. Paths are relative to the project folder.
+// Returns undefined, and writes nothing, until every scene has its voiceover.
+export function buildManifest(project: Project, plan: ScenePlan): AssetManifest | undefined {
+  const voiceovers = project.readJsonOr<Record<string, Voiceover>>(FILES.voiceovers, {});
+  if (plan.scenes.some((s) => !voiceovers[s.id])) return undefined;
+  const images = project.readJsonOr<Record<string, string>>(FILES.images, {});
+  const footage = project.footage();
+  const byId = new Map(project.assets().map((a) => [a.id, a]));
+
+  const layout = layoutScenes(plan.scenes.map((s) => voiceovers[s.id].durationSec));
+  let totalFrames = layout.totalFrames;
+  if (footage) {
+    const footageFrames = Math.floor((footage.durationSec ?? 0) * FPS);
+    if (layout.totalFrames > footageFrames) {
+      throw new Error(`The voiceover (${(layout.totalFrames / FPS).toFixed(1)}s) is longer than the footage (${(footageFrames / FPS).toFixed(1)}s). Use a longer clip or shorten the script.`);
+    }
+    totalFrames = footageFrames;
+  }
+
+  const manifest: AssetManifest = {
+    fps: FPS,
+    ...dimensionsFor(plan.aspect, footage),
+    totalFrames,
+    ...(footage ? { footageKey: footage.key } : {}),
+    scenes: plan.scenes.map((scene, i) => ({
+      id: scene.id,
+      startFrame: layout.scenes[i].startFrame,
+      durationFrames: layout.scenes[i].durationFrames,
+      voiceoverKey: voiceovers[scene.id].key,
+      words: voiceovers[scene.id].words,
+      ...(scene.treatment === "illustration" && images[scene.id] ? { imageKey: images[scene.id] } : {}),
+      userAssetKeys: scene.userAssetIds.map((id) => {
+        const a = byId.get(id);
+        if (!a) throw new Error(`Scene ${scene.id} references unknown asset ${id}. Add it with \`reelkit assets upload\`.`);
+        return a.key;
+      }),
+    })),
+  };
+  project.writeJson(FILES.manifest, manifest);
+  return manifest;
+}
+
+// The gate before building: everything the plan asks for must be on disk.
+export function missingAssets(project: Project, plan: ScenePlan): string[] {
+  const voiceovers = project.readJsonOr<Record<string, Voiceover>>(FILES.voiceovers, {});
+  const images = project.readJsonOr<Record<string, string>>(FILES.images, {});
+  const problems: string[] = [];
+  for (const s of plan.scenes) {
+    if (!voiceovers[s.id]) problems.push(`Scene ${s.id} has no voiceover.`);
+    else if (voiceoverStale(voiceovers[s.id], s, plan)) problems.push(`Scene ${s.id}'s voiceover is out of date. Run \`reelkit assets voiceover --all\`.`);
+    else if (!project.exists(voiceovers[s.id].key)) problems.push(`Missing file: ${voiceovers[s.id].key}`);
+    // Only an illustration scene uses an image; one left over from an earlier plan is not needed.
+    if (s.treatment === "illustration") {
+      if (!images[s.id]) problems.push(`Scene ${s.id} has no image.`);
+      else if (!project.exists(images[s.id])) problems.push(`Missing file: ${images[s.id]}`);
+    }
+  }
+  return problems;
+}

package/src/project/probe.ts

@@ -0,0 +1,54 @@
+import { execFile } from "node:child_process";
+import { stat } from "node:fs/promises";
+import { basename, extname } from "node:path";
+import { promisify } from "node:util";
+
+const run = promisify(execFile);
+
+const IMAGE_EXT: Record<string, string> = { ".png": "image/png", ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".webp": "image/webp", ".gif": "image/gif", ".svg": "image/svg+xml" };
+const VIDEO_EXT: Record<string, string> = { ".mp4": "video/mp4", ".mov": "video/quicktime", ".webm": "video/webm" };
+const AUDIO_EXT: Record<string, string> = { ".mp3": "audio/mpeg", ".wav": "audio/wav", ".m4a": "audio/mp4" };
+
+// What an audio-only file with a video extension is called when it is uploaded.
+const AUDIO_IN_VIDEO: Record<string, string> = { ".mp4": "audio/mp4", ".webm": "audio/webm", ".mov": "audio/quicktime" };
+
+type Probed = { kind: "image" | "video" | "audio"; contentType: string; bytes: number; width?: number; height?: number; durationSec?: number };
+
+// The kind comes from the file extension, from an allow-list. ffprobe only reads the dimensions and the length.
+// Every failure is a one-line Error written for the person who gave the file.
+export async function probeFile(path: string): Promise<Probed> {
+  const name = basename(path);
+  const ext = extname(path).toLowerCase();
+  const kind = IMAGE_EXT[ext] ? "image" : VIDEO_EXT[ext] ? "video" : AUDIO_EXT[ext] ? "audio" : undefined;
+  if (!kind) throw new Error(`${name} is not a supported file type. Use an image (png, jpg, webp, gif, svg), a video (mp4, mov, webm) or audio (mp3, wav, m4a).`);
+  const contentType = IMAGE_EXT[ext] ?? VIDEO_EXT[ext] ?? AUDIO_EXT[ext];
+  const bytes = await stat(path).then((s) => s.size, () => { throw new Error(`${name} does not exist. Check the path.`); });
+  if (ext === ".svg") return { kind, contentType, bytes };
+
+  const unreadable = new Error(`${name} could not be read. It may be damaged. Try exporting it again.`);
+  let info: { streams?: { codec_type?: string; width?: number; height?: number }[]; format?: { duration?: string } };
+  try {
+    const { stdout } = await run("ffprobe", ["-v", "error", "-print_format", "json", "-show_format", "-show_streams", path]);
+    info = JSON.parse(stdout);
+  } catch (e) {
+    if ((e as NodeJS.ErrnoException)?.code === "ENOENT") throw new Error("ffprobe was not found. Install ffmpeg (macOS: `brew install ffmpeg`) and try again.");
+    throw unreadable;
+  }
+  const v = info.streams?.find((s) => s.codec_type === "video");
+  const a = info.streams?.find((s) => s.codec_type === "audio");
+  const duration = info.format?.duration ? Number(info.format.duration) : undefined;
+  // ffprobe guesses from the extension and can "succeed" on junk with a 0x0 picture.
+  const sized = v && (v.width ?? 0) > 0 && (v.height ?? 0) > 0;
+  if (kind === "image") {
+    if (!sized) throw unreadable;
+    return { kind, contentType, bytes, width: v!.width, height: v!.height };
+  }
+  if (kind === "video") {
+    // A recording with sound and no picture is audio, not a damaged video.
+    if (!sized && a) return { kind: "audio", contentType: AUDIO_IN_VIDEO[ext], bytes, durationSec: duration };
+    if (!sized) throw unreadable;
+    return { kind, contentType, bytes, width: v!.width, height: v!.height, durationSec: duration };
+  }
+  if (!a) throw unreadable;
+  return { kind, contentType, bytes, durationSec: duration };
+}

package/src/project/project.ts

@@ -0,0 +1,58 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve, sep } from "node:path";
+import { z } from "zod";
+import { AspectSchema, type AssetRecord } from "../pipeline/schema";
+
+export const FILES = {
+  config: "reelkit.json", plan: "plan.json", manifest: "manifest.json",
+  assetIndex: "assets/index.json", voiceovers: "assets/voiceovers.json", images: "assets/images.json", library: "assets/library.json",
+} as const;
+
+// "path: message", or just the message for a problem at the root of the file.
+export const issueLines = (e: { issues: { path: PropertyKey[]; message: string }[] }) =>
+  e.issues.map((i) => (i.path.length ? `${i.path.map(String).join(".")}: ${i.message}` : i.message));
+
+export const ProjectConfigSchema = z.object({ aspect: AspectSchema, name: z.string().optional(), footage: z.string().optional() });
+export type ProjectConfig = z.infer<typeof ProjectConfigSchema>;
+
+// One video's working folder. Every command reads and writes its state here.
+export class Project {
+  constructor(readonly dir: string) {}
+  // The one place a project-relative path becomes a real path, so nothing can reach outside the folder.
+  path(rel: string) {
+    const root = resolve(this.dir);
+    const full = resolve(root, rel);
+    if (full !== root && !full.startsWith(root + sep)) throw new Error(`"${rel}" is outside the project folder. Reelkit only reads and writes inside the project.`);
+    return join(this.dir, rel);
+  }
+  exists(rel: string) { return existsSync(this.path(rel)); }
+  readJson<T>(rel: string): T {
+    const text = readFileSync(this.path(rel), "utf8");
+    try {
+      return JSON.parse(text) as T;
+    } catch (e) {
+      throw new Error(`${rel} is not valid JSON: ${e instanceof Error ? e.message : String(e)}. Fix the file and run the command again.`);
+    }
+  }
+  readJsonOr<T>(rel: string, fallback: T): T { return this.exists(rel) ? this.readJson<T>(rel) : fallback; }
+  writeJson(rel: string, value: unknown) {
+    mkdirSync(dirname(this.path(rel)), { recursive: true });
+    writeFileSync(this.path(rel), JSON.stringify(value, null, 2) + "\n");
+  }
+  config(): ProjectConfig {
+    const parsed = ProjectConfigSchema.safeParse(this.readJson(FILES.config));
+    if (!parsed.success) throw new Error(`${FILES.config} is not valid: ${issueLines(parsed.error)[0]}. Fix it or run \`reelkit init\` in a new folder.`);
+    return parsed.data;
+  }
+  assets(): AssetRecord[] { return this.readJsonOr<AssetRecord[]>(FILES.assetIndex, []); }
+  footage(): AssetRecord | undefined {
+    const id = this.config().footage;
+    return id ? this.assets().find((a) => a.id === id) : undefined;
+  }
+}
+
+export function openProject(cwd: string): Project {
+  const p = new Project(cwd);
+  if (!p.exists(FILES.config)) throw new Error("Not a Reelkit project. Run `reelkit init` here first.");
+  return p;
+}