Add -r name=id relationship flag to api and create

[shwetamurali]

Description

-a key=value builds a JSON:API request body without hand-writing JSON, but it only ever populates data.attributes, the create help tells users that anything needing a relationships block must fall back to -i with a full body. This adds the missing piece.

-r name=id populates data.relationships on both tfctl api and tfctl create:

tfctl create workspace -a name=foo -r project=prj-12dff4673ab9
{ "data": {
  "type": "workspaces",
  "attributes": { "name": "foo" },
  "relationships": {
    "project": { "data": { "type": "projects", "id": "prj-12dff4673ab9" } }
  }
}}

• The flag key is the relationship name, and the linkage type is inferred from the OpenAPI schema.
• To find the type, the resolver follows the request body's allOf/oneOf/items down to the identifier's type enum. The same part tells us whether a relationship is to-one or to-many, so to-many ones take comma-separated ids and to-one ones reject a second id.
• Ambiguous / unknown relationships require an explicit -r name:type=id override. Ambiguous ones are those the schema pins to more than one type (e.g. locked-bycan be users, teams, or runs.)
• Unknown relationship names produce a helpful error listing the valid names for that endpoint.
• create: -i is now mutually exclusive with both -a and -r.

Example Output

Type inferred from the schema, the key is project but the linkage type is projects:

$ tfctl create workspace -a name=my-workspace -r project=prj-12dff4673ab9 --dry-run
{
  "data": {
    "type": "workspaces",
    "attributes": { "name": "my-workspace" },
    "relationships": {
      "project": {
        "data": { "type": "projects", "id": "prj-12dff4673ab9" }
      }
    }
  }
}

Using the type as the key errors and points you at the right name:

$ tfctl api /organizations/my-org/workspaces -r projects=prj-1 --dry-run
ERROR: unknown relationship "projects" for this endpoint; valid relationships:
agent-pool, current-assessment-result, current-configuration-version, current-run,
current-state-version, latest-run, organization, outputs, project, readme, ssh-key, vars
(or override with -r projects:<type>=<id>)

For relationships the schema can't pin to one type, pass it explicitly with name:type=id:

$ tfctl api /organizations/my-org/workspaces -r locked-by:users=user-abc --dry-run
{
  "data": {
    "type": "workspaces",
    "relationships": {
      "locked-by": {
        "data": { "type": "users", "id": "user-abc" }
      }
    }
  }
}

PR Checklist

• Run npx changie new or install changie to prepare a new changelog entry for the next set of release notes.
• Ensure any command changes are sensitive to these global flags:
  • --json — Force machine readable output to stdout. Does not apply to stderr.
  • --markdown — Force markdown output to stdout. Does not apply to stderr.
  • --dry-run — Don't make any actual writes or other mutations. Describe what would have changed to stderr.
  • --quiet — Only render essential content.
• Get the logging interface from the context and add debug logging for interesting conditions and nonfatal situations.
• Run make gen/screenshot if the root command output changes.
• Add the Autocomplete field to positional arguments and flags to assist shell autocomplete.

PCI review checklist

• I have documented a clear reason for, and description of, the change I am making.

• If applicable, I've documented a plan to revert these changes if they require more than reverting the pull request.

• If applicable, I've documented the impact of any changes to security controls.

  Examples of changes to security controls include using new access control methods, adding or removing logging pipelines, etc.