[spydon]

Description

Every flame_cli command that prints a result now takes --json, so that scripts and AI coding agents never have to parse prose. That is all of them except run, which passes its arguments on to flutter run (which has --machine for this). Before this PR only tree, inspect and overlays had it.

With --json the result is printed as a single JSON value on stdout. For example, snapshot prints the path, width, height, pixel ratio and byte size of the image. diff prints the differing and total pixels, the percentage, the bounds and the output path. pause, resume and step print the paused state, and step adds the frames and times. debug prints the debug mode and its target. overlay show/hide/only print the overlay and its state, and input tap/drag/key print what was sent. reload and restart print ok, message and all output lines. logs prints the log path and the last lines, and create prints the name, path and template. devtools --json starts dart devtools --machine, so its output is one JSON object per line. --json cannot be combined with logs --follow.

When a command called with --json fails, FlameCommandRunner.run prints {"error": {"message": ..., "exitCode": ..., "kind": ...}} instead of the text message, with the same exit code as without --json. The kind is the name of the exit code (usage, data, unavailable, software, cantCreate). The error also goes to stdout, so stdout of a --json command always holds exactly one JSON value, either the result or the error. Other output that is not the result, such as the output of flutter in flame create or the "enabled the extension" notice of devtools, goes to stderr in JSON mode. Arguments that fail to parse are also reported as JSON when --json is among them.

--json is a per command flag rather than a global one on FlameCommandRunner. With package:args, global flags have to come before the command name, so a global flag would not have supported flame tree --json as it works today. The shared plumbing lives in json_output.dart: addJsonFlag, a JsonOutput mixin with jsonOutput and writeResult(result, text), and jsonError. FlameCommand adds the flag and mixes in JsonOutput itself, so new commands that talk to the game get --json without extra work. Other commands call addJsonFlag and mix in JsonOutput. A test checks that every command except run has the flag. FlameCommand now also uses the GameConnector that is passed to FlameCommandRunner, so the game commands can be tested with a fake connection.

The exit code usage was audited and was already consistent with the docs. The docs now list every exit code with its kind, including 1 from diff --exit-code. They also have a new section about using the CLI from scripts and agents, which describes the result of every command.

Changes that scripts could notice:

• The --json help text of tree, inspect and overlays is now the shared one. Their JSON output is unchanged.
• In text mode, diff --output no longer prints the summary before failing when the diff image cannot be written. Only the error is printed now.
• Otherwise the text output and exit codes without --json are unchanged.

Checklist

• I have followed the Contributor Guide when preparing my PR.
• I have updated/added tests for ALL new/updated/fixed functionality.
• I have updated/added relevant documentation in docs and added dartdoc comments with ///.
• [-] I have updated/added relevant examples in examples or docs.

Breaking Change?

• Yes, this PR is a breaking change.
• No, this PR is not a breaking change.

Related Issues

Part of #4131