{"record":{"id":"7f56c08852d91e2a","repo":"heygen-com/hyperframes","slug":"apply-requires-grading-json","errorCode":null,"errorMessage":"--apply requires --grading <json>","messagePattern":"--apply requires --grading <json>","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/cli/src/commands/media-treatment.ts","lineNumber":522,"sourceCode":"    ? 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;\n  capability?: string;\n  all?: boolean;\n  project?: string;","sourceCodeStart":504,"sourceCodeEnd":540,"githubUrl":"https://github.com/heygen-com/hyperframes/blob/c2996c8626135db5253519359d8a063d3bafad8d/packages/cli/src/commands/media-treatment.ts#L504-L540","documentation":"Thrown by parseGrading when --apply is set but --grading <json> is not provided. The --apply flag is an explicit verb that requires a payload to apply; without --grading there is nothing to write. The CLI rejects this rather than silently no-oping.","triggerScenarios":"Running `hyperframes media-treatment --selector '#hero' --apply` with no --grading value. Common in agent flows that set --apply as a marker but forget to attach the grading JSON.","commonSituations":"Agent command builders that conditionally attach --apply but miss the --grading payload. Users who assume --apply alone re-applies a previous grading.","solutions":["Provide a grading payload: `--grading '<json>' --apply`","If you meant to clear, use `--clear` instead of `--apply`","Use `--capabilities` or `--capability <id>` to discover valid grading shapes"],"exampleFix":"// before\nhyperframes media-treatment --selector '#hero' --apply\n// after\nhyperframes media-treatment --selector '#hero' --grading '{\"preset\":\"warm-daylight\"}' --apply","handlingStrategy":"validation","validationCode":"function requireGradingForApply(apply?: boolean, grading?: string, clear?: boolean): void {\n  if (apply && !clear && grading === undefined) {\n    throw new Error('--apply requires --grading <json>');\n  }\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Treat --apply and --grading as a required pair","Use --dry-run alongside --apply --grading to preview safely"],"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"}