{"record":{"id":"410c0fe0256ded6d","repo":"heygen-com/hyperframes","slug":"capabilities-cannot-be-combined-with-mutation-op","errorCode":null,"errorMessage":"--capabilities cannot be combined with mutation options","messagePattern":"--capabilities cannot be combined with mutation options","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/cli/src/commands/media-treatment.ts","lineNumber":562,"sourceCode":"  grading?: string;\n  apply?: boolean;\n  analyze?: boolean;\n  clear?: boolean;\n  \"dry-run\"?: boolean;\n  json?: boolean;\n}\n\nfunction runCapabilityQuery(args: MediaTreatmentCommandArgs): void {\n  const capability = readOptionalString(args.capability);\n  const hasMutationOption = [\n    readOptionalString(args.selector),\n    readOptionalString(args.grading),\n    args.clear,\n    args[\"dry-run\"],\n    args.apply,\n    args.analyze,\n  ].some(Boolean);\n  if (hasMutationOption) throw new Error(\"--capabilities cannot be combined with mutation options\");\n  if (args.all === true && capability)\n    throw new Error(\"Use either --all or --capability, not both\");\n\n  let capabilities: unknown = getMediaTreatmentCapabilityOverview();\n  if (args.all === true) capabilities = getHfColorGradingCapabilities();\n  else if (capability) capabilities = getMediaTreatmentCapabilityDetail(capability);\n  console.log(JSON.stringify(withMeta({ ok: true, capabilities }), null, 2));\n}\n\nfunction resolveMutationFile(args: MediaTreatmentCommandArgs) {\n  const project = resolveProject(readOptionalString(args.project));\n  const fileArg = readOptionalString(args.file) ?? \"index.html\";\n  const filePath = resolve(project.dir, fileArg);\n  if (!isPathInside(filePath, project.dir) || !filePath.toLowerCase().endsWith(\".html\")) {\n    throw new Error(\"--file must be an HTML file inside the project\");\n  }\n  if (!existsSync(filePath)) throw new Error(`Composition file not found: ${fileArg}`);\n  return { project, filePath };","sourceCodeStart":544,"sourceCodeEnd":580,"githubUrl":"https://github.com/heygen-com/hyperframes/blob/c2996c8626135db5253519359d8a063d3bafad8d/packages/cli/src/commands/media-treatment.ts#L544-L580","documentation":"Thrown by runCapabilityQuery when --capabilities (or --capability/--all) is combined with any mutation or analysis option (--selector, --grading, --clear, --dry-run, --apply, --analyze). Capability queries are read-only introspection and must run alone; mixing them with mutations is rejected to prevent ambiguous intent.","triggerScenarios":"Commands like `hyperframes media-treatment --capabilities --selector '#hero'` or `--capability wheels --apply`. The presence of any truthy mutation flag alongside a capability query triggers this.","commonSituations":"Agent command builders that always append --capabilities for context. Users exploring capabilities while reusing a command template that has mutation flags. Flags leaking from a shared base command string.","solutions":["Run the capability query on its own: `hyperframes media-treatment --capabilities`","Run the mutation as a separate command without --capabilities/--capability/--all","Strip all mutation flags before issuing a capability introspection call"],"exampleFix":"// before\nhyperframes media-treatment --capabilities --selector '#hero' --apply\n// after — split into two commands\nhyperframes media-treatment --capabilities\nhyperframes media-treatment --selector '#hero' --grading '{\"preset\":\"warm\"}' --apply","handlingStrategy":"validation","validationCode":"function assertCapabilityQueryIsolated(args: { capabilities?: boolean; capability?: string; all?: boolean; selector?: string; grading?: string; clear?: boolean; apply?: boolean; analyze?: boolean; 'dry-run'?: boolean }): void {\n  const isCap = args.capabilities || !!args.capability || args.all;\n  const hasMutation = args.selector || args.grading || args.clear || args.apply || args.analyze || args['dry-run'];\n  if (isCap && hasMutation) {\n    throw new Error('Capability queries must run without mutation/analysis flags');\n  }\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Use dedicated command templates for introspection vs. mutation","Strip mutation flags before any capability query call"],"tags":["media-treatment","cli","argument-conflict","validation"],"backgroundTag":null,"analyzedSha":"c2996c8626135db5253519359d8a063d3bafad8d","analyzedAt":"2026-08-12T22:18:56.877Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}