json output documentation and tests

[schacon]

It would be nice to have the json fields documented and tests that ensure that they are provided.

[Byron]

I am thinking that we already use schemars, which is what all the AI compatibility layers use to help AI to interact with tools automatically.

What if we'd make that a thing in the but-api, so its types are either naturally JSON compatible, or can be converted with one .into()?

Currently schemars looks like this:

gitbutler/crates/but-action/src/grouping.rs

Lines 44 to 53 in fba0faf

	#[derive(Debug, Serialize, Deserialize, JsonSchema)]
	#[schemars(deny_unknown_fields)]
	pub struct BranchCreation {
	#[schemars(description = "The name of the branch to create.")]
	pub branch_name: String,
	#[schemars(
	description = "A detailed description of the changes in this branch, including the files changed and the commit messages."
	)]
	pub description: String,
	}

But it turns out they can look like this:

/// Probably this is picked up too!
#[derive(Debug, Serialize, Deserialize, JsonSchema)]
#[schemars(deny_unknown_fields)]
pub struct BranchCreation {
    /// The name of the branch to create
    pub branch_name: String,
    /// ### This is the schema title
    ///
    /// And what follows is the description. We can use `markdown` of course.
    /// A detailed description of the changes in this branch, including the files changed and the commit messages.
    pub description: String,
}

Then these JSON schemas look like this, in the simple case:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "User",
  "description": "A simple user object with name and email.",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "The user's full name. Must be at least 2 characters."
    },
    "email": {
      "type": "string",
      "format": "email",
      "description": "The user's email address. Must be valid."
    }
  },
  "required": ["name", "email"]
}

Which means we can use this information as introspection of the structure, and turn it into something that looks good in a terminal, which sounds like something that AI can write and that can be well tested.

CC @krlvi and @estib-vega for opinions, and alternatives.

[Byron]

And thinking about it more… I believe it's wise to keep these JSON compatible types and all the heft that comes with it away from the but-api and define them in a separate crate, while making conversions between but-api types (which could be plumbing types) and the JSON types easy (and compile-time safe).

But most importantly, this separation allows to version the JSON types separately in preparation to keep them stable. Thus we could deliver a 1.0 of the CLI with stable types even while but-api is still changing.