reelkit-cli 0.1.0

package/src/commands/assets.ts

@@ -0,0 +1,196 @@
+import { randomUUID } from "node:crypto";
+import { copyFileSync, mkdirSync, readFileSync } from "node:fs";
+import { basename, dirname, resolve } from "node:path";
+import { download, uploadTo } from "../api/client";
+import { client, type Ctx, type Result } from "../context";
+import { LibraryKindSchema, UploadKindSchema } from "../contract";
+import { PACE_SPEED, type AssetManifest, type AssetRecord, type ScenePlan } from "../pipeline/schema";
+import { buildManifest, voiceoverStale, type Voiceover } from "../project/manifest";
+import { loadPlan } from "./plan";
+import { FILE_NAME } from "../render/validate";
+import { probeFile } from "../project/probe";
+import { FILES, openProject, type Project } from "../project/project";
+
+export type LibraryEntry = { path: string; kind: string; title: string; meta: Record<string, unknown> };
+
+// A failure to lay out the timeline after a paid call must not hide that the call succeeded and was saved.
+function tryManifest(project: Project, plan: ScenePlan): { manifest?: AssetManifest; note?: string } {
+  try {
+    return { manifest: buildManifest(project, plan) };
+  } catch (e) {
+    return { note: `The timeline could not be built yet: ${e instanceof Error ? e.message : String(e)}` };
+  }
+}
+
+function recordPull(project: Project, id: string, entry: LibraryEntry) {
+  project.writeJson(FILES.library, { ...project.readJsonOr<Record<string, LibraryEntry>>(FILES.library, {}), [id]: entry });
+}
+
+export function setSceneImage(project: Project, sceneId: string, path: string) {
+  project.writeJson(FILES.images, { ...project.readJsonOr<Record<string, string>>(FILES.images, {}), [sceneId]: path });
+}
+
+// Registers one of the user's own files. It stays on this machine unless --share is given.
+export async function assetsUpload(ctx: Ctx, file: string, opts: { describe?: string; footage?: boolean; share?: boolean; kind?: string; tags?: string }): Promise<Result> {
+  const project = openProject(ctx.cwd);
+  if (opts.share && opts.kind === "component") return { ok: false, summary: "Components cannot be shared from the CLI yet. Share images, overlays, sound effects, music or clips." };
+  const source = resolve(ctx.cwd, file);
+  let probe: Awaited<ReturnType<typeof probeFile>>;
+  try {
+    probe = await probeFile(source);
+  } catch (e) {
+    return { ok: false, summary: e instanceof Error ? e.message : String(e) };
+  }
+  if (opts.footage && probe.kind !== "video") return { ok: false, summary: `${file} is ${probe.kind}, not a video, so it cannot be the footage.` };
+  const kind = opts.share ? UploadKindSchema.safeParse(opts.kind) : undefined;
+  if (opts.share && (!kind?.success || !opts.describe)) return { ok: false, summary: "Sharing needs --kind (image, overlay, sfx, music or clip) and --describe \"what it is\"." };
+
+  const id = `a-${randomUUID().slice(0, 8)}`;
+  const filename = basename(source).replace(/[^A-Za-z0-9._-]/g, "_");
+  const key = `assets/user/${id}-${filename}`;
+  mkdirSync(dirname(project.path(key)), { recursive: true });
+  copyFileSync(source, project.path(key));
+  const record: AssetRecord = { id, filename, key, ...probe, ...(opts.describe ? { description: opts.describe } : {}), createdAt: new Date().toISOString() };
+  project.writeJson(FILES.assetIndex, [...project.assets(), record]);
+  if (opts.footage) project.writeJson(FILES.config, { ...project.config(), footage: id });
+
+  let libraryId: string | undefined;
+  if (opts.share && kind?.success) {
+    const api = client(ctx);
+    const tags = (opts.tags ?? "").split(",").map((t) => t.trim()).filter(Boolean);
+    const { width, height, durationSec } = probe;
+    const up = await api("libraryUpload", {
+      kind: kind.data, title: filename, description: opts.describe!, tags, meta: { width, height, durationSec },
+      filename, contentType: probe.contentType, bytes: probe.bytes, shareable: true,
+    });
+    await uploadTo(up.uploadUrl, new Uint8Array(readFileSync(source)), probe.contentType);
+    libraryId = (await api("libraryCommit", { id: up.id })).item.id;
+  }
+  return {
+    ok: true, data: { ...record, ...(libraryId ? { libraryId } : {}) },
+    summary: `Added ${filename} as ${id} (${probe.kind})${opts.footage ? ", set as the footage" : ""}${libraryId ? `, shared to the library as ${libraryId} (awaiting review)` : ", private to this project"}.`,
+  };
+}
+
+export async function assetsSearch(ctx: Ctx, query: string, opts: { kind?: string; limit?: string }): Promise<Result> {
+  const kind = opts.kind === undefined ? undefined : LibraryKindSchema.safeParse(opts.kind);
+  if (kind && !kind.success) return { ok: false, summary: `Unknown kind "${opts.kind}". Use one of: ${LibraryKindSchema.options.join(", ")}.` };
+  const { items } = await client(ctx)("librarySearch", { q: query, ...(kind?.success ? { kind: kind.data } : {}), ...(opts.limit ? { limit: Number(opts.limit) } : {}) });
+  return {
+    ok: true, data: { items },
+    summary: items.length
+      ? items.map((i) => `${`${Math.round(i.match * 100)}%`.padStart(4)}  ${i.id}  ${i.kind}  ${i.title}: ${i.description}  [${i.tags.join(", ")}]`).join("\n")
+      : "No matches in the library. Generate it instead.",
+  };
+}
+
+// The contract already limits file names to plain ones; this is the second lock, before a name becomes a path.
+export function unsafeName(name: string, kind: string): boolean {
+  if (name !== basename(name) || name === "." || name === ".." || /[\\/]/.test(name)) return true;
+  return kind === "component" && (!FILE_NAME.test(name) || name === "Video.tsx");
+}
+
+export async function assetsPull(ctx: Ctx, id: string, opts: { scene?: string; force?: boolean }): Promise<Result> {
+  const project = openProject(ctx.cwd);
+  if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(id)) return { ok: false, summary: `"${id}" is not a library id. Copy the id from \`reelkit assets search\`.` };
+  if (opts.scene) {
+    // Checked before anything is downloaded.
+    const illustrations = loadPlan(project).scenes.filter((s) => s.treatment === "illustration").map((s) => s.id);
+    if (!illustrations.includes(opts.scene)) {
+      return { ok: false, summary: `Scene ${opts.scene} is not an illustration scene in plan.json. ${illustrations.length ? `The illustration scenes are: ${illustrations.join(", ")}.` : "The plan has no illustration scenes."}` };
+    }
+  }
+  const pulled = await client(ctx)("libraryPull", { id });
+  if (unsafeName(pulled.filename, pulled.item.kind)) return { ok: false, summary: `The library returned an unsafe file name for ${id}, so nothing was written. Report this item.` };
+  if (opts.scene && pulled.item.kind !== "image") return { ok: false, summary: `${id} is ${pulled.item.kind}, not an image, so it cannot be a scene's image.` };
+  // A component is code, not media: it goes beside Video.tsx, which may only import files in src/.
+  if (pulled.item.kind === "component") {
+    const path = `src/${pulled.filename}`;
+    if (project.exists(path) && !opts.force) return { ok: false, summary: `${path} already exists. Use --force to replace it with the library version.` };
+    await download(pulled.url, project.path(path));
+    recordPull(project, id, { path, kind: "component", title: pulled.item.title, meta: pulled.item.meta });
+    const name = pulled.filename.replace(/\.tsx$/, "");
+    const example = typeof pulled.item.meta.example === "string" ? `\nExample: ${pulled.item.meta.example}` : "";
+    return { ok: true, data: { path, kind: "component" }, summary: `Pulled ${id} to ${path}. Use it with: import { ${name} } from "./${name}";${example}` };
+  }
+  const path = `assets/lib/${id}/${pulled.filename}`;
+  await download(pulled.url, project.path(path));
+  recordPull(project, id, { path, kind: pulled.item.kind, title: pulled.item.title, meta: pulled.item.meta });
+  let note: string | undefined;
+  if (opts.scene) {
+    setSceneImage(project, opts.scene, path);
+    if (project.exists(FILES.plan)) note = tryManifest(project, loadPlan(project)).note;
+  }
+  return {
+    ok: true, data: { path, kind: pulled.item.kind },
+    summary: [
+      opts.scene ? `Pulled ${id} as the image for scene ${opts.scene}.` : `Pulled ${id} to ${path}. Reference it in the composition as urls["${path}"].`,
+      ...(note ? [note] : []),
+    ].join("\n"),
+  };
+}
+
+export async function assetsVoices(ctx: Ctx): Promise<Result> {
+  const { voices } = await client(ctx)("voices", {});
+  return {
+    ok: true, data: { voices },
+    summary: voices.map((v) => `${v.id}  ${v.name} (${[v.gender, v.accent, v.language].filter(Boolean).join(", ")}): ${v.description}`).join("\n"),
+  };
+}
+
+// One voice and pace for the whole video, as chosen in the plan. A scene already recorded is skipped unless --redo.
+export async function assetsVoiceover(ctx: Ctx, opts: { scene?: string; all?: boolean; redo?: boolean }): Promise<Result> {
+  const project = openProject(ctx.cwd);
+  const plan = loadPlan(project);
+  if (!opts.all && !opts.scene) return { ok: false, summary: "Say which scene with --scene <id>, or use --all." };
+  const wanted = opts.all ? plan.scenes : plan.scenes.filter((s) => s.id === opts.scene);
+  if (!wanted.length) return { ok: false, summary: `No scene with id ${opts.scene}. The scenes are: ${plan.scenes.map((s) => s.id).join(", ")}.` };
+
+  const api = client(ctx);
+  const done = project.readJsonOr<Record<string, Voiceover>>(FILES.voiceovers, {});
+  const todo = wanted.filter((s) => opts.redo || !done[s.id] || voiceoverStale(done[s.id], s, plan));
+  const rerecorded = todo.filter((s) => done[s.id] && voiceoverStale(done[s.id], s, plan)).length;
+  // One at a time: the result of each is saved before the next starts, so a failure or an exhausted quota loses nothing.
+  for (const scene of todo) {
+    const speed = PACE_SPEED[plan.pace ?? "normal"];
+    const vo = await api("voiceover", { text: scene.narration, ...(plan.voiceId ? { voiceId: plan.voiceId } : {}), speed });
+    const key = `assets/vo-${scene.id}.${vo.ext}`;
+    await download(vo.url, project.path(key));
+    done[scene.id] = { key, durationSec: vo.durationSec, words: vo.words, text: scene.narration, ...(plan.voiceId ? { voiceId: plan.voiceId } : {}), speed };
+    project.writeJson(FILES.voiceovers, done);
+    ctx.log(`Recorded scene ${scene.id} (${vo.durationSec.toFixed(1)}s)`);
+  }
+  const { manifest, note } = tryManifest(project, plan);
+  const left = plan.scenes.filter((s) => !done[s.id] || voiceoverStale(done[s.id], s, plan)).map((s) => s.id);
+  const recorded = `Recorded ${todo.length} scene(s)${rerecorded ? ` (${rerecorded} re-recorded because the script or voice changed)` : ""}.`;
+  return {
+    ok: true, data: { recorded: todo.map((s) => s.id), rerecorded, voiceovers: done, totalSeconds: manifest ? manifest.totalFrames / manifest.fps : null },
+    summary: [
+      manifest
+        ? `${recorded} The video runs ${(manifest.totalFrames / manifest.fps).toFixed(1)}s. Voiceover files are in assets/.${left.length ? ` Still out of date: ${left.join(", ")}. Run \`reelkit assets voiceover --all\`.` : ""}`
+        : `${recorded}${left.length ? ` Still to record: ${left.join(", ")}.` : ""}`,
+      ...(note ? [note] : []),
+    ].join("\n"),
+  };
+}
+
+export async function assetsGenImage(ctx: Ctx, prompt: string | undefined, opts: { scene: string; redo?: boolean }): Promise<Result> {
+  const project = openProject(ctx.cwd);
+  const plan = loadPlan(project);
+  const scene = plan.scenes.find((s) => s.id === opts.scene);
+  if (!scene || scene.treatment !== "illustration" || !scene.imagePrompt) return { ok: false, summary: `Scene ${opts.scene} is not an illustration scene, so it does not take an image.` };
+  // A scene that already has its image is not charged for again, whatever prompt is given; only --redo asks for a new one.
+  const have = project.readJsonOr<Record<string, string>>(FILES.images, {})[scene.id];
+  if (have && project.exists(have) && !opts.redo) return { ok: true, data: { path: have, skipped: true }, summary: `Scene ${scene.id} already has an image at ${have}. Use --redo to generate a new one.` };
+  // Anything tied to the user's footage or uploads stays private, whatever the plan says. So does a prompt changed by hand.
+  const shareable = scene.shareable && !project.footage() && scene.userAssetIds.length === 0 && !prompt;
+  const img = await client(ctx)("images", { prompt: prompt ?? scene.imagePrompt, aspect: plan.aspect, shareable, tags: scene.imageTags });
+  const path = `assets/img-${scene.id}.${img.ext}`;
+  await download(img.url, project.path(path));
+  setSceneImage(project, scene.id, path);
+  const { note } = tryManifest(project, plan);
+  return {
+    ok: true, data: { path, libraryId: img.libraryId ?? null },
+    summary: [`Generated the image for scene ${scene.id} at ${path}${img.libraryId ? `, and shared it to the library as ${img.libraryId} (awaiting review)` : ""}.`, ...(note ? [note] : [])].join("\n"),
+  };
+}

package/src/commands/auth.ts

@@ -0,0 +1,118 @@
+import { hostname } from "node:os";
+import { ensureSkill } from "../agents";
+import { ApiFailure, type Api } from "../api/client";
+import { apiUrl, client, type Ctx, type Result } from "../context";
+import { clearCredentials, clearPendingLogin, loadCredentials, loadPendingLogin, saveCredentials, savePendingLogin } from "../credentials";
+
+const FINISH_WAIT_SEC = 60;
+
+const MAX_SERVER_ERRORS = 3;
+
+// Asks for the token until it is approved, expired or the time runs out: asks first, then waits, so an approval already given is found at once.
+// A poll that fails on the server is tried again, but the third failure in a row ends the wait with that error's message;
+// an answer of any kind (including "pending") starts the count again.
+// Whatever interval the API asks for, it is never shorter than a second, and the number of tries is finite.
+async function pollForToken(ctx: Ctx, api: Api, deviceCode: string, intervalSec: number, waitSec: number): Promise<{ status: "approved"; token: string } | { status: "expired" | "timeout" } | { status: "unreachable"; message: string }> {
+  const interval = Math.max(1, intervalSec);
+  const attempts = Math.max(1, Math.ceil(waitSec / interval));
+  let failures = 0;
+  for (let i = 0; i < attempts; i++) {
+    if (i > 0) await ctx.sleep(interval * 1000);
+    try {
+      const poll = await api("deviceToken", { deviceCode });
+      failures = 0;
+      if (poll.status !== "pending") return poll;
+    } catch (e) {
+      if (!(e instanceof ApiFailure && e.code === "server_error")) throw e;
+      if (++failures >= MAX_SERVER_ERRORS) return { status: "unreachable", message: e.message };
+    }
+  }
+  return { status: "timeout" };
+}
+
+const done = (ctx: Ctx, token: string): Result => {
+  saveCredentials(ctx.env, { token });
+  clearPendingLogin(ctx.env);
+  ensureSkill(ctx);
+  return { ok: true, summary: "Logged in." };
+};
+
+// The link that opens the login page with the code already filled in: the verification URL with `code` added to its query, keeping what
+// it already has.
+function completeUrl(verificationUrl: string, userCode: string): string {
+  try {
+    const u = new URL(verificationUrl);
+    u.searchParams.set("code", userCode);
+    return u.toString();
+  } catch {
+    return `${verificationUrl}${verificationUrl.includes("?") ? "&" : "?"}code=${encodeURIComponent(userCode)}`;
+  }
+}
+
+const sameOrigin = (a: string, b: string): boolean => {
+  try { return new URL(a).origin === new URL(b).origin; } catch { return false; }
+};
+
+// `browser: false` is --no-browser; `json` is the global --json. The browser opens only for a person at a terminal: stdout is a TTY, no
+// --json, no --no-browser and no REELKIT_NO_BROWSER=1.
+export async function authLogin(ctx: Ctx, opts: { start?: boolean; finish?: boolean; browser?: boolean; json?: boolean } = {}): Promise<Result> {
+  if (opts.start && opts.finish) return { ok: false, summary: "Use --start or --finish, not both." };
+  const api = client(ctx);
+  if (opts.finish) return authFinish(ctx, api);
+  const start = await api("deviceStart", { label: hostname().slice(0, 80) });
+  if (opts.start) {
+    savePendingLogin(ctx.env, { deviceCode: start.deviceCode, userCode: start.userCode, verificationUrl: start.verificationUrl, intervalSec: start.intervalSec, expiresAt: Date.now() + start.expiresInSec * 1000 });
+    const verificationUrlComplete = completeUrl(start.verificationUrl, start.userCode);
+    return {
+      ok: true, data: { verificationUrl: start.verificationUrl, verificationUrlComplete, userCode: start.userCode, expiresInSec: start.expiresInSec },
+      summary: `Ask the user to open ${verificationUrlComplete} and approve the login (the code is ${start.userCode}). When they have approved it, run \`reelkit auth login --finish\`.`,
+    };
+  }
+  const link = completeUrl(start.verificationUrl, start.userCode);
+  ctx.log(`Open ${link}`);
+  ctx.log(`Code: ${start.userCode}`);
+  if (ctx.isTTY && !opts.json && opts.browser !== false && ctx.env.REELKIT_NO_BROWSER !== "1" && ctx.openUrl) {
+    if (sameOrigin(start.verificationUrl, apiUrl(ctx))) {
+      // The link is already printed, so a browser that cannot be opened costs nothing.
+      try { await ctx.openUrl(link); } catch { ctx.log("Could not open a browser. Open the link above yourself."); }
+    } else {
+      ctx.log("The login page is on a different site than the API, so it was not opened automatically. Check the link before opening it.");
+    }
+  }
+  const res = await pollForToken(ctx, api, start.deviceCode, start.intervalSec, start.expiresInSec);
+  if (res.status === "approved") return done(ctx, res.token);
+  if (res.status === "unreachable") return { ok: false, summary: res.message };
+  return { ok: false, summary: res.status === "expired" ? "The code expired. Run `reelkit auth login` again." : "Login timed out. Run `reelkit auth login` again." };
+}
+
+async function authFinish(ctx: Ctx, api: Api): Promise<Result> {
+  const pending = loadPendingLogin(ctx.env);
+  if (!pending) return { ok: false, summary: "No login is in progress. Run `reelkit auth login --start` first." };
+  if (pending.expiresAt <= Date.now()) {
+    clearPendingLogin(ctx.env);
+    return { ok: false, summary: "The login code expired. Run `reelkit auth login --start` again." };
+  }
+  const res = await pollForToken(ctx, api, pending.deviceCode, pending.intervalSec, FINISH_WAIT_SEC);
+  if (res.status === "approved") return done(ctx, res.token);
+  if (res.status === "unreachable") return { ok: false, summary: res.message };
+  if (res.status === "expired") {
+    clearPendingLogin(ctx.env);
+    return { ok: false, summary: "The login code expired. Run `reelkit auth login --start` again." };
+  }
+  return { ok: false, summary: "Not approved yet. Approve the code in the browser, then run `reelkit auth login --finish` again." };
+}
+
+export async function authLogout(ctx: Ctx): Promise<Result> {
+  if (loadCredentials(ctx.env)) await client(ctx)("revoke", {}).catch(() => undefined);
+  clearCredentials(ctx.env);
+  return { ok: true, summary: "Logged out." };
+}
+
+export async function whoami(ctx: Ctx): Promise<Result> {
+  const me = await client(ctx)("me", {});
+  const q = me.quota;
+  return {
+    ok: true, data: me,
+    summary: `${me.handle}\nVoiceover: ${q.voiceoverChars.used}/${q.voiceoverChars.limit} characters\nImages: ${q.images.used}/${q.images.limit}\nResets: ${q.resetsAt.slice(0, 10)}\nContributions: ${me.contributions}`,
+  };
+}

package/src/commands/build.ts

@@ -0,0 +1,109 @@
+import { execFile } from "node:child_process";
+import { mkdirSync, readdirSync, readFileSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { promisify } from "node:util";
+import type { Ctx, Result } from "../context";
+import type { AssetManifest } from "../pipeline/schema";
+import { buildManifest, missingAssets } from "../project/manifest";
+import { openProject, type Project } from "../project/project";
+import { mediaUrls, serveDir } from "../project/serve";
+import { bundleProject, disposeBundle, renderStills, renderVideo, writeEntry } from "../render/render";
+import { FILE_NAME, MAIN_FILE, staticCheck, typecheck } from "../render/validate";
+import { loadPlan } from "./plan";
+
+const exec = promisify(execFile);
+const MEDIA_PATH = /["'`](assets\/[^"'`\s]+\.(?:mp3|wav|m4a|mp4|mov|webm|png|jpe?g|webp|svg|gif))["'`]/g;
+
+// Everything that can be known without rendering: the assets are there, the code follows the rules, the types are right.
+function inspect(project: Project): { errors: string[]; manifest?: AssetManifest } {
+  const plan = loadPlan(project);
+  const names = readdirSync(project.path("src")).filter((f) => f.endsWith(".tsx"));
+  if (!names.includes(MAIN_FILE)) return { errors: [`src/${MAIN_FILE} has not been written.`] };
+  const errors: string[] = missingAssets(project, plan);
+  for (const name of names) {
+    if (!FILE_NAME.test(name)) { errors.push(`src/${name}: a component file must be PascalCase, such as NumberBadge.tsx.`); continue; }
+    const source = readFileSync(project.path(join("src", name)), "utf8");
+    errors.push(...staticCheck(source, name, names));
+    // Test frames do not load audio, so a sound the project does not hold would only fail at the final render.
+    for (const m of source.matchAll(MEDIA_PATH)) {
+      if (!project.exists(m[1])) errors.push(`${name} uses "${m[1]}", which is not in this project. Get it with \`reelkit assets pull <id>\` first.`);
+    }
+  }
+  if (errors.length) return { errors };
+  const typeErrors = typecheck(names.map((n) => project.path(join("src", n))));
+  if (typeErrors.length) return { errors: typeErrors };
+  const manifest = buildManifest(project, plan);
+  return manifest ? { errors: [], manifest } : { errors: ["The manifest could not be built. Run `reelkit assets voiceover --all`."] };
+}
+
+const failed = (errors: string[]): Result => ({ ok: false, data: { errors }, summary: `${errors.length} problem(s):\n- ${errors.join("\n- ")}` });
+
+export async function check(ctx: Ctx): Promise<Result> {
+  const { errors } = inspect(openProject(ctx.cwd));
+  return errors.length ? failed(errors) : { ok: true, data: { errors: [] }, summary: "The composition passes. Run `reelkit preview` to see it." };
+}
+
+// Bundles the composition and serves the project's media for as long as fn runs.
+async function withBundle<T>(project: Project, fn: (serveUrl: string, urls: Record<string, string>) => Promise<T>): Promise<T> {
+  const server = await serveDir(project.dir);
+  let serveUrl: string | undefined;
+  try {
+    serveUrl = await bundleProject(await writeEntry(project.dir));
+    return await fn(serveUrl, mediaUrls(project, server));
+  } finally {
+    try {
+      if (serveUrl) await disposeBundle(serveUrl);
+    } finally {
+      await server.close();
+    }
+  }
+}
+
+const ffmpegToJpeg = (png: string, jpg: string) => exec("ffmpeg", ["-y", "-loglevel", "error", "-i", png, "-vf", "scale=540:-2", "-q:v", "5", jpg]).then(() => undefined);
+
+export async function preview(ctx: Ctx, deps: { toJpeg?: (png: string, jpg: string) => Promise<void> } = {}): Promise<Result> {
+  const toJpeg = deps.toJpeg ?? ffmpegToJpeg;
+  const project = openProject(ctx.cwd);
+  const { errors, manifest } = inspect(project);
+  if (!manifest) return failed(errors);
+  const dir = project.path("out/preview");
+  rmSync(dir, { recursive: true, force: true });
+  mkdirSync(dir, { recursive: true });
+  const mids = manifest.scenes.map((s) => ({ sceneId: s.id, frame: s.startFrame + Math.floor(s.durationFrames / 2) }));
+  try {
+    try {
+      await withBundle(project, (serveUrl, urls) => renderStills(serveUrl, { manifest, urls }, mids.map((m) => m.frame), dir));
+    } catch (e) {
+      return failed([`Render failed: ${e instanceof Error ? e.message : String(e)}`]);
+    }
+    const frames: { sceneId: string; path: string }[] = [];
+    try {
+      for (const m of mids) {
+        // Shrunk to phone width: small enough to read cheaply, and what is unreadable here is unreadable on a phone.
+        const path = `out/preview/${m.sceneId}.jpg`;
+        await toJpeg(join(dir, `still-${m.frame}.png`), project.path(path));
+        frames.push({ sceneId: m.sceneId, path });
+      }
+    } catch {
+      return failed(["Could not write the preview frames: ffmpeg failed. Check that ffmpeg is installed (macOS: `brew install ffmpeg`) and run `reelkit preview` again."]);
+    }
+    return { ok: true, data: { frames }, summary: `One frame per scene, taken at its midpoint:\n${frames.map((f) => `${f.sceneId}: ${f.path}`).join("\n")}` };
+  } finally {
+    // The full-size stills are only inputs; none stays behind however this ends.
+    for (const f of readdirSync(dir)) if (/^still-\d+\.png$/.test(f)) rmSync(join(dir, f), { force: true });
+  }
+}
+
+export async function render(ctx: Ctx): Promise<Result> {
+  const project = openProject(ctx.cwd);
+  const { errors, manifest } = inspect(project);
+  if (!manifest) return failed(errors);
+  const path = "out/video.mp4";
+  try {
+    await withBundle(project, (serveUrl, urls) => renderVideo(serveUrl, { manifest, urls }, project.path(path)));
+  } catch (e) {
+    return failed([`Render failed: ${e instanceof Error ? e.message : String(e)}`]);
+  }
+  const seconds = manifest.totalFrames / manifest.fps;
+  return { ok: true, data: { path, seconds }, summary: `Video: ${project.path(path)} (${seconds.toFixed(1)}s, ${manifest.width}x${manifest.height})` };
+}

package/src/commands/init.ts

@@ -0,0 +1,32 @@
+import { execFile } from "node:child_process";
+import { existsSync, mkdirSync, statSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { promisify } from "node:util";
+import { ensureSkill } from "../agents";
+import type { Ctx, Result } from "../context";
+import { AspectSchema } from "../pipeline/schema";
+import { FILES, Project } from "../project/project";
+
+const exec = promisify(execFile);
+const DIRS = ["assets", "refs", "src", "out"];
+
+export async function init(ctx: Ctx, name: string | undefined, opts: { aspect?: string }): Promise<Result> {
+  const slug = name === undefined ? undefined : name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+  if (slug === "") return { ok: false, summary: "Give the project a name with letters or digits, for example: reelkit init launch-video" };
+  const aspect = AspectSchema.safeParse(opts.aspect ?? "9:16");
+  if (!aspect.success) return { ok: false, summary: `Unknown aspect "${opts.aspect}". Use 9:16, 16:9 or 1:1.` };
+  if (Number(process.versions.node.split(".")[0]) < 20) return { ok: false, summary: `Node 20 or newer is needed; this is ${process.versions.node}. Install a newer Node.` };
+  try { await exec("ffmpeg", ["-version"]); } catch { return { ok: false, summary: "ffmpeg was not found. Install it (macOS: `brew install ffmpeg`) and run `reelkit init` again." }; }
+
+  const dir = slug ? join(ctx.cwd, slug) : ctx.cwd;
+  if (slug && existsSync(dir) && !statSync(dir).isDirectory()) return { ok: false, summary: `A file named ${slug} is in the way. Choose another project name or remove it.` };
+  const project = new Project(dir);
+  for (const d of DIRS) mkdirSync(project.path(d), { recursive: true });
+  if (!project.exists(FILES.config)) project.writeJson(FILES.config, { aspect: aspect.data, ...(name !== undefined && { name }) });
+  if (!existsSync(project.path(".gitignore"))) writeFileSync(project.path(".gitignore"), ".reelkit\nout\nrefs\n");
+  ensureSkill(ctx);
+  return {
+    ok: true, data: { dir, config: project.config() },
+    summary: `Project ready in ${dir} (${project.config().aspect}).${slug ? ` Next: cd ${slug}` : ""}`,
+  };
+}

package/src/commands/install.ts

@@ -0,0 +1,24 @@
+import { AGENTS, installSkill } from "../agents";
+import type { Ctx, Result } from "../context";
+
+export async function install(ctx: Ctx, opts: { agent?: string; force?: boolean }, extra: { source?: string } = {}): Promise<Result> {
+  const ids = AGENTS.map((a) => a.id);
+  let agents: string[] | undefined;
+  if (opts.agent === "all") agents = ids;
+  else if (opts.agent) {
+    if (!ids.includes(opts.agent)) return { ok: false, summary: `Unknown agent "${opts.agent}". Use one of: ${ids.join(", ")}, or all.` };
+    agents = [opts.agent];
+  }
+  let report;
+  try { report = installSkill(ctx.env, { agents, force: opts.force, source: extra.source }); }
+  catch (e) { return { ok: false, summary: (e instanceof Error ? e.message : String(e)).split("\n")[0] }; }
+  if (!report.installed.length && report.skipped.every((s) => s.reason === "not installed on this machine") && !agents) {
+    return { ok: false, summary: `No coding agent was found on this machine. Name one with --agent (${ids.join(", ")}).` };
+  }
+  const name = (id: string) => AGENTS.find((a) => a.id === id)!.name;
+  const lines = [
+    ...report.installed.map((i) => `Installed the Reelkit skill for ${name(i.agent)}: ${i.path}`),
+    ...report.skipped.filter((s) => agents || s.reason !== "not installed on this machine").map((s) => `Skipped ${name(s.agent)}: ${s.reason}`),
+  ];
+  return { ok: true, data: report, summary: lines.join("\n") };
+}

package/src/commands/plan.ts

@@ -0,0 +1,45 @@
+import { client, type Ctx, type Result } from "../context";
+import { loadCredentials } from "../credentials";
+import { reviewPlan } from "../pipeline/review";
+import { ScenePlanSchema, validatePlan, type ScenePlan } from "../pipeline/schema";
+import { FILES, issueLines, openProject, type Project } from "../project/project";
+
+export function loadPlan(project: Project): ScenePlan {
+  if (!project.exists(FILES.plan)) throw new Error("There is no plan.json in this project. Write the plan first.");
+  const parsed = ScenePlanSchema.safeParse(project.readJson(FILES.plan));
+  if (!parsed.success) throw new Error(`plan.json is not valid. Run \`reelkit plan check\`. ${issueLines(parsed.error)[0]}`);
+  // The rules that need no network, so nothing is paid for on a plan that cannot become a video.
+  const footage = project.footage();
+  const problems = validatePlan(parsed.data, { aspect: project.config().aspect, footage, assets: project.assets().filter((a) => a.id !== footage?.id) });
+  if (problems.length) throw new Error(`plan.json has problems. Run \`reelkit plan check\`. ${problems[0]}`);
+  return parsed.data;
+}
+
+// Hard rules (mustFix) stop the video; soft notes (shouldImprove) are advice for a better script.
+export async function planCheck(ctx: Ctx): Promise<Result> {
+  const project = openProject(ctx.cwd);
+  if (!project.exists(FILES.plan)) throw new Error("There is no plan.json in this project. Write the plan first.");
+  let raw: unknown;
+  try {
+    raw = project.readJson(FILES.plan);
+  } catch (e) {
+    const message = e instanceof Error ? e.message : String(e);
+    return { ok: false, data: { mustFix: [message], shouldImprove: [] }, summary: `plan.json has 1 problem(s) to fix:\n- ${message}` };
+  }
+  const parsed = ScenePlanSchema.safeParse(raw);
+  if (!parsed.success) {
+    const mustFix = issueLines(parsed.error);
+    return { ok: false, data: { mustFix, shouldImprove: [] }, summary: `plan.json has ${mustFix.length} problem(s) to fix:\n- ${mustFix.join("\n- ")}` };
+  }
+  const footage = project.footage();
+  const assets = project.assets().filter((a) => a.id !== footage?.id);
+  const voiceIds = loadCredentials(ctx.env) ? (await client(ctx)("voices", {})).voices.map((v) => v.id) : undefined;
+  const mustFix = validatePlan(parsed.data, { aspect: project.config().aspect, footage, assets, voiceIds });
+  const shouldImprove = mustFix.length ? [] : reviewPlan(parsed.data, { footage });
+  const lines = [
+    mustFix.length ? `Fix these:\n- ${mustFix.join("\n- ")}` : "The plan is valid.",
+    ...(shouldImprove.length ? [`Worth improving:\n- ${shouldImprove.join("\n- ")}`] : []),
+    ...(voiceIds ? [] : ["The voice was not checked because you are not logged in. Run `reelkit auth login`."]),
+  ];
+  return { ok: mustFix.length === 0, data: { mustFix, shouldImprove }, summary: lines.join("\n") };
+}

package/src/context.ts

@@ -0,0 +1,21 @@
+import { createClient, type Api } from "./api/client";
+import { DEFAULT_API_URL, loadCredentials } from "./credentials";
+
+export type Ctx = {
+  cwd: string;
+  env: Record<string, string | undefined>;
+  // Progress lines for a person watching. The final answer is the command's Result, not a log line.
+  log(line: string): void;
+  sleep(ms: number): Promise<void>;
+  // Whether a person is watching this terminal (stdout is a TTY). Tests set it explicitly.
+  isTTY: boolean;
+  // Opens a web page for the person. Absent where there is nothing to open it with (tests); never required for a command to work.
+  openUrl?: (url: string) => Promise<boolean | void>;
+};
+export type Result = { ok: boolean; summary: string; data?: unknown };
+
+export const apiUrl = (ctx: Ctx) => ctx.env.REELKIT_API_URL || DEFAULT_API_URL;
+
+export function client(ctx: Ctx): Api {
+  return createClient({ baseUrl: apiUrl(ctx), token: loadCredentials(ctx.env)?.token });
+}