{"record":{"id":"aa75f6489b386359","repo":"heygen-com/hyperframes","slug":"analyze-cannot-be-combined-with-mutation-options","errorCode":null,"errorMessage":"--analyze cannot be combined with mutation options","messagePattern":"--analyze cannot be combined with mutation options","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/cli/src/commands/media-treatment.ts","lineNumber":593,"sourceCode":"  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 };\n}\n\nfunction analyzeTarget(args: MediaTreatmentCommandArgs) {\n  const { project, filePath } = resolveMutationFile(args);\n  const selector = readOptionalString(args.selector);\n  if (!selector) throw new Error(\"--selector is required\");\n  if (\n    readOptionalString(args.grading) ||\n    args.clear === true ||\n    args.apply === true ||\n    args[\"dry-run\"] === true\n  ) {\n    throw new Error(\"--analyze cannot be combined with mutation options\");\n  }\n  const selectorIndex = parseSelectorIndex(readOptionalString(args[\"selector-index\"]));\n  const { element, tag } = selectMediaElement(\n    readFileSync(filePath, \"utf8\"),\n    selector,\n    selectorIndex,\n  );\n  const source = mediaSourceForElement(element);\n  const compositionFile = relative(project.dir, filePath).split(\"\\\\\").join(\"/\");\n  const mediaPath = resolveMediaTreatmentSource(project.dir, compositionFile, source);\n  return {\n    ok: true,\n    action: \"analyze\",\n    file: compositionFile || \"index.html\",\n    selector,\n    selectorIndex: selectorIndex ?? 0,\n    tag,\n    media: source,","sourceCodeStart":575,"sourceCodeEnd":611,"githubUrl":"https://github.com/heygen-com/hyperframes/blob/c2996c8626135db5253519359d8a063d3bafad8d/packages/cli/src/commands/media-treatment.ts#L575-L611","documentation":"Thrown by analyzeTarget when --analyze is combined with any of --grading, --clear, --apply, or --dry-run. Analysis is a read-only measurement pass; mutation flags imply a write intent. The two modes are mutually exclusive to keep the command's effect unambiguous.","triggerScenarios":"Commands like `hyperframes media-treatment --selector '#hero' --analyze --apply` or `--analyze --grading '{...}'` or `--analyze --dry-run`.","commonSituations":"Agents that chain exploration and mutation in one command. Users who add --dry-run to --analyze thinking it previews a mutation. Flags reused from a prior apply command.","solutions":["Run analysis alone: `--selector '#hero' --analyze`","Run mutation separately: `--selector '#hero' --grading '<json>' --apply`","To preview a mutation without writing, use `--apply --dry-run` (not --analyze)"],"exampleFix":"// before\nhyperframes media-treatment --selector '#hero' --analyze --grading '{\"preset\":\"warm\"}'\n// after — analyze read-only\nhyperframes media-treatment --selector '#hero' --analyze","handlingStrategy":"validation","validationCode":"function assertAnalyzeIsolated(args: { analyze?: boolean; grading?: string; clear?: boolean; apply?: boolean; 'dry-run'?: boolean }): void {\n  if (args.analyze && (args.grading || args.clear || args.apply || args['dry-run'])) {\n    throw new Error('--analyze cannot combine with mutation flags');\n  }\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Run analysis and mutation as separate command invocations","Use --apply --dry-run (not --analyze) to preview a mutation"],"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"}