{"record":{"id":"36346e7e75f34c3d","repo":"heygen-com/hyperframes","slug":"grading-requires-apply","errorCode":null,"errorMessage":"--grading requires --apply","messagePattern":"--grading requires --apply","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/cli/src/commands/media-treatment.ts","lineNumber":519,"sourceCode":"  const cleanSource = cleanAssetUrl(sourceUrl);\n  if (!cleanSource) throw new Error(\"Selected media has no analyzable local src\");\n  const projectRelative = cleanSource.startsWith(\"/\")\n    ? cleanSource\n    : rewriteAssetPath(compositionFile, cleanSource, (path) => existsSync(join(projectDir, path)));\n  const asset = resolveExistingLocalAsset(projectDir, projectRelative);\n  if (!asset) throw new Error(`Media file not found: ${source}`);\n  return asset.resolved;\n}\n\nfunction parseGrading(raw: string | undefined, apply: boolean, clear: boolean): unknown {\n  if (clear) {\n    if (raw !== undefined || apply) {\n      throw new Error(\"Use either --apply with --grading or --clear, not both\");\n    }\n    return undefined;\n  }\n  if (!apply) {\n    if (raw !== undefined) throw new Error(\"--grading requires --apply\");\n    throw new Error(\"Use --apply with --grading <json> or --clear\");\n  }\n  if (raw === undefined) throw new Error(\"--apply requires --grading <json>\");\n  try {\n    return JSON.parse(raw);\n  } catch (error) {\n    throw new Error(`Could not parse --grading JSON: ${normalizeErrorMessage(error)}`);\n  }\n}\n\nfunction mutationVerb(action: \"apply\" | \"clear\", changed: boolean, dryRun: boolean): string {\n  if (dryRun) return `Would ${action}`;\n  if (!changed) return action === \"apply\" ? \"Already applied\" : \"Already clear\";\n  return action === \"apply\" ? \"Applied\" : \"Cleared\";\n}\n\ninterface MediaTreatmentCommandArgs {\n  capabilities?: boolean;","sourceCodeStart":501,"sourceCodeEnd":537,"githubUrl":"https://github.com/heygen-com/hyperframes/blob/c2996c8626135db5253519359d8a063d3bafad8d/packages/cli/src/commands/media-treatment.ts#L501-L537","documentation":"Thrown by parseGrading when --grading <json> is supplied without --apply and without --clear. The --grading value is a mutation payload; the CLI requires an explicit action verb (--apply) to commit it. Providing grading alone is treated as an incomplete, potentially accidental command.","triggerScenarios":"Running `hyperframes media-treatment --selector '#hero' --grading '{\"preset\":\"warm\"}'` with no --apply and no --clear flag.","commonSituations":"Agents omitting --apply assuming grading implies application. Users testing a dry-run who forget --apply --dry-run. Copy-paste that drops the trailing flag.","solutions":["Add --apply to commit the grading: `--grading '<json>' --apply`","Add --apply --dry-run to preview without writing","If you intended to remove grading, drop --grading and use --clear instead"],"exampleFix":"// before\nhyperframes media-treatment --selector '#hero' --grading '{\"preset\":\"warm\"}'\n// after\nhyperframes media-treatment --selector '#hero' --grading '{\"preset\":\"warm\"}' --apply","handlingStrategy":"validation","validationCode":"function requireApplyForGrading(grading?: string, apply?: boolean, clear?: boolean): void {\n  if (!clear && !apply && grading !== undefined) {\n    throw new Error('--grading requires --apply or --clear');\n  }\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always pair --grading with an explicit action verb (--apply or --clear)","Validate the flag triple before spawning the CLI"],"tags":["media-treatment","cli","missing-flag","validation"],"backgroundTag":null,"analyzedSha":"c2996c8626135db5253519359d8a063d3bafad8d","analyzedAt":"2026-08-12T22:18:56.877Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}