feat(cli): zod-validate Edit JSON before render and studio

Author: dazzatronus

bun.lock

@@ -28,7 +28,9 @@
     "test": "bun test"
   },
   "dependencies": {
-    "commander": "^12.1.0"
+    "@shotstack/schemas": "^1.10.10",
+    "commander": "^12.1.0",
+    "zod": "^4.4.3"
   },
   "devDependencies": {
     "@types/bun": "latest",

package.json

@@ -7,6 +7,7 @@ import { resolveEnv, ENV_NAMES } from "../http/env.ts";
 import { emit, parseOutputFormat } from "../output.ts";
 import { withRecording, commandArgv } from "../recorder.ts";
 import { pollStatus } from "./status.ts";
+import { validateEdit, formatIssues } from "../lib/validate.ts";
 
 interface RenderResponse {
   success: boolean;
@@ -30,6 +31,13 @@ export const renderCommand = new Command("render")
       const raw = await readFile(path, "utf8");
       const template = JSON.parse(raw) as unknown;
 
+      const validation = validateEdit(template);
+      if (!validation.ok) {
+        if (format === "json") console.log(JSON.stringify({ ok: false, issues: validation.issues }));
+        else console.error(formatIssues(validation.issues));
+        return { exitCode: 1, validation };
+      }
+
       const client = createClient({ apiKey, env });
       const result = await client.post<RenderResponse>("/render", template);
       const id = result.response.id;

src/commands/render.ts

@@ -3,6 +3,7 @@ import { resolve } from "node:path";
 import { spawn, execSync } from "node:child_process";
 import { Command } from "commander";
 import { emit, parseOutputFormat } from "../output.ts";
+import { validateEdit, formatIssues } from "../lib/validate.ts";
 
 const STUDIO_URL = "https://shotstack.studio";
 const SHARE_API_URL = `${STUDIO_URL}/api/share`;
@@ -24,7 +25,13 @@ export const studioCommand = new Command("studio")
     const path = resolve(process.cwd(), file);
     const raw = await readFile(path, "utf8");
     const template = JSON.parse(raw) as unknown;
-    assertTemplateShape(template);
+
+    const validation = validateEdit(template);
+    if (!validation.ok) {
+      if (format === "json") console.log(JSON.stringify({ ok: false, issues: validation.issues }));
+      else console.error(formatIssues(validation.issues));
+      process.exit(1);
+    }
 
     const { url, shortened } = await buildStudioUrl(template, { shorten: options.shorten });
 
@@ -82,12 +89,6 @@ async function tryShortenViaStudio(template: unknown): Promise<string | null> {
   }
 }
 
-function assertTemplateShape(t: unknown): asserts t is { timeline: unknown; output: unknown } {
-  if (!t || typeof t !== "object") throw new Error("Template must be a JSON object.");
-  if (!("timeline" in t)) throw new Error("Template missing required field: timeline.");
-  if (!("output" in t)) throw new Error("Template missing required field: output.");
-}
-
 async function copyToClipboard(text: string): Promise<void> {
   const { cmd, args } = clipboardCommand();
   await new Promise<void>((res, rej) => {

src/commands/studio.ts

@@ -0,0 +1,89 @@
+import { editSchema } from "@shotstack/schemas/zod";
+import type { ZodError, ZodIssue } from "zod";
+
+export interface ValidationIssue {
+  path: string;
+  code: string;
+  message: string;
+  suggestion?: string;
+}
+
+export type ValidationResult =
+  | { ok: true }
+  | { ok: false; issues: ValidationIssue[] };
+
+const KEY_SUGGESTIONS: Record<string, string> = {
+  alignment: "align",
+  duration: "length",
+  transitions: "transition",
+  name: "family",
+};
+
+const VALUE_SUGGESTIONS: Record<string, Record<string, string>> = {
+  "align.vertical": { center: "middle" },
+  fit: { cover: "crop" },
+};
+
+export function validateEdit(input: unknown): ValidationResult {
+  const result = editSchema.safeParse(input);
+  if (result.success) return { ok: true };
+  return { ok: false, issues: toIssues(result.error) };
+}
+
+export function formatIssues(issues: ValidationIssue[]): string {
+  const lines = ["✗ Edit JSON failed validation:"];
+  for (const issue of issues) {
+    const hint = issue.suggestion ? ` (did you mean '${issue.suggestion}'?)` : "";
+    lines.push(`  ${issue.path || "<root>"}: ${issue.message}${hint}`);
+  }
+  return lines.join("\n");
+}
+
+function toIssues(error: ZodError): ValidationIssue[] {
+  return error.issues.flatMap((issue) => expandIssue(issue));
+}
+
+function expandIssue(issue: ZodIssue): ValidationIssue[] {
+  const basePath = formatPath(issue.path);
+
+  if (issue.code === "unrecognized_keys" && "keys" in issue) {
+    return issue.keys.map((key) => ({
+      path: appendKey(basePath, key),
+      code: issue.code,
+      message: `unrecognized key '${key}'`,
+      suggestion: KEY_SUGGESTIONS[key],
+    }));
+  }
+
+  const suggestion = lookupValueSuggestion(basePath, issue);
+
+  return [
+    {
+      path: basePath,
+      code: issue.code,
+      message: issue.message,
+      ...(suggestion ? { suggestion } : {}),
+    },
+  ];
+}
+
+function lookupValueSuggestion(path: string, issue: ZodIssue): string | undefined {
+  const semanticPath = path.replace(/\[\d+\]/g, "");
+  const tail = semanticPath.split(".").slice(-2).join(".");
+  if (issue.code === "invalid_value" && "received" in issue) {
+    const received = String(issue.received);
+    return VALUE_SUGGESTIONS[tail]?.[received] ?? VALUE_SUGGESTIONS[semanticPath]?.[received];
+  }
+  return undefined;
+}
+
+function formatPath(parts: ReadonlyArray<string | number>): string {
+  return parts.reduce<string>((acc, part) => {
+    if (typeof part === "number") return `${acc}[${part}]`;
+    return acc ? `${acc}.${part}` : part;
+  }, "");
+}
+
+function appendKey(base: string, key: string): string {
+  return base ? `${base}.${key}` : key;
+}

src/lib/validate.ts

@@ -0,0 +1,85 @@
+import { describe, test, expect } from "bun:test";
+import { validateEdit, formatIssues } from "../src/lib/validate.ts";
+
+const validEdit = {
+  timeline: {
+    tracks: [
+      {
+        clips: [
+          {
+            asset: { type: "rich-text", text: "hi", font: { family: "Roboto", size: 22 } },
+            start: 0,
+            length: 1,
+          },
+        ],
+      },
+    ],
+  },
+  output: { format: "mp4", size: { width: 1280, height: 720 } },
+};
+
+describe("validateEdit", () => {
+  test("accepts a minimal valid edit", () => {
+    expect(validateEdit(validEdit)).toEqual({ ok: true });
+  });
+
+  test("rejects unrecognized keys with did-you-mean for CSS-instinct names", () => {
+    const bad = structuredClone(validEdit);
+    (bad.timeline.tracks[0]!.clips[0]!.asset as Record<string, unknown>).alignment = "center";
+
+    const result = validateEdit(bad);
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+
+    const issue = result.issues.find((i) => i.path.endsWith("alignment"));
+    expect(issue).toBeDefined();
+    expect(issue!.code).toBe("unrecognized_keys");
+    expect(issue!.suggestion).toBe("align");
+    expect(issue!.path).toBe("timeline.tracks[0].clips[0].asset.alignment");
+  });
+
+  test("rejects wrong types with descriptive messages", () => {
+    const result = validateEdit({ timeline: "nope", output: { format: "mp4" } });
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+
+    const timelineIssue = result.issues.find((i) => i.path === "timeline");
+    expect(timelineIssue).toBeDefined();
+    expect(timelineIssue!.message).toMatch(/expected object/i);
+  });
+
+  test("rejects missing required fields", () => {
+    const result = validateEdit({ timeline: { tracks: [] } });
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+
+    const outputIssue = result.issues.find((i) => i.path === "output");
+    expect(outputIssue).toBeDefined();
+  });
+
+  test("formats array indices with bracket notation", () => {
+    const bad = structuredClone(validEdit);
+    (bad.timeline.tracks[0]!.clips[0]!.asset as Record<string, unknown>).duration = 5;
+
+    const result = validateEdit(bad);
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+
+    const issue = result.issues[0]!;
+    expect(issue.path).toMatch(/tracks\[0\]\.clips\[0\]/);
+    expect(issue.suggestion).toBe("length");
+  });
+});
+
+describe("formatIssues", () => {
+  test("renders a multi-line stderr-friendly summary", () => {
+    const issues = [
+      { path: "timeline.tracks[0]", code: "x", message: "bad", suggestion: "good" },
+      { path: "output.format", code: "y", message: "wrong" },
+    ];
+    const formatted = formatIssues(issues);
+    expect(formatted).toContain("✗ Edit JSON failed validation:");
+    expect(formatted).toContain("timeline.tracks[0]: bad (did you mean 'good'?)");
+    expect(formatted).toContain("output.format: wrong");
+  });
+});