{"record":{"id":"6fc1b58a03f07129","repo":"heygen-com/hyperframes","slug":"for-path-is-required","errorCode":null,"errorMessage":"--for <path> is required","messagePattern":"--for <path> is required","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/cli/src/commands/grade-compare.ts","lineNumber":269,"sourceCode":"\n// The ungraded frame as a leading reference cell. An empty grading object\n// normalizes to inactive, so the runtime renders the source image untouched —\n// giving the agent a baseline to judge every candidate look against.\nexport function prependBaselineCell(cells: GradeCompareCell[]): GradeCompareCell[] {\n  return [validateCell(\"original\", {}), ...cells];\n}\n\nexport function parseGradeCompareArgs(args: {\n  for?: unknown;\n  grades?: unknown;\n  luts?: unknown;\n  project?: unknown;\n  out?: unknown;\n  json?: unknown;\n  timeout?: unknown;\n}): ParsedGradeCompareArgs {\n  const frameArg = readOptionalString(args.for);\n  if (!frameArg) throw new Error(\"--for <path> is required\");\n\n  const gradesArg = readOptionalString(args.grades);\n  const lutsArg = readOptionalString(args.luts);\n  if (Boolean(gradesArg) === Boolean(lutsArg)) {\n    throw new Error(\"Exactly one of --grades or --luts is required\");\n  }\n\n  const projectDir = resolve(readOptionalString(args.project) ?? process.cwd());\n  const framePath = resolveFromBase(projectDir, frameArg);\n  const outPath = resolveFromBase(projectDir, readOptionalString(args.out) ?? \"grade-compare.png\");\n\n  return {\n    framePath,\n    projectDir,\n    outPath,\n    source: gradesArg\n      ? { kind: \"grades\", path: resolveFromBase(projectDir, gradesArg) }\n      : { kind: \"luts\", value: lutsArg ?? \"\" },","sourceCodeStart":251,"sourceCodeEnd":287,"githubUrl":"https://github.com/heygen-com/hyperframes/blob/c2996c8626135db5253519359d8a063d3bafad8d/packages/cli/src/commands/grade-compare.ts#L251-L287","documentation":"Thrown by parseGradeCompareArgs when `--for` is absent or empty. `--for` is the reference frame (image or video) onto which every candidate grade is rendered, so without it the command has nothing to compare against. readOptionalString returns undefined for missing/empty values, which trips the guard.","triggerScenarios":"Invoking `hyperframes grade-compare` without `--for`, or with `--for \"\"`. Also triggered programmatically by calling parseGradeCompareArgs({}) or parseGradeCompareArgs({ for: \"\" }).","commonSituations":"Forgetting the flag (note: citty's own `required: true` should catch the CLI path, but programmatic callers and some argument forms bypass it); passing an unset shell variable `$FRAME` that expands to empty.","solutions":["Add `--for <path>` pointing at an image (.png/.jpg) or video (.mp4/.mov/etc.) file.","If the path is relative, remember it resolves against `--project` (default cwd) — verify the file exists there.","For programmatic callers, pass a non-empty `for` string to parseGradeCompareArgs."],"exampleFix":"# before\nhyperframes grade-compare --grades grades.json\n# after\nhyperframes grade-compare --for frame.png --grades grades.json","handlingStrategy":"validation","validationCode":"// Before calling parseGradeCompareArgs programmatically\nif (!args.for || String(args.for).trim() === \"\") {\n  throw new Error(\"--for <path> is required\");\n}\nconst parsed = parseGradeCompareArgs(args);","typeGuard":"function hasForArg(args: { for?: unknown }): args is { for: string } {\n  return typeof args.for === \"string\" && args.for.trim() !== \"\";\n}","tryCatchPattern":"try {\n  const parsed = parseGradeCompareArgs({ for: args.for, /* ... */ });\n} catch (err) {\n  if (/--for/.test((err as Error).message)) console.error(\"Missing --for; pass a reference frame path.\");\n  throw err;\n}","preventionTips":["Make --for the first flag in your command to avoid dropping it during edits.","In scripts, assert the frame path exists before invoking grade-compare.","When calling parseGradeCompareArgs, narrow with hasForArg first."],"tags":["cli","input-validation","grade-compare","required-arg"],"backgroundTag":null,"analyzedSha":"c2996c8626135db5253519359d8a063d3bafad8d","analyzedAt":"2026-08-12T22:18:56.877Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}