Add container run hostname flag

[thromel]

Type of Change

• Bug fix
• New feature
• Breaking change
• Documentation update

Motivation and Context

Apple container run and container create currently use the container name as the guest hostname through the first network attachment. Docker Compose also has a separate hostname: field, where the requested guest hostname can differ from the container management name.

This PR adds --hostname <hostname> to the shared management flags and uses it as the hostname for the first network attachment. The Linux runtime already derives the guest hostname from the first attachment hostname, so the change uses the existing persisted network attachment model rather than introducing a separate container configuration field.

Design status

This is separate from the alias work in #1815/#1839. Aliases may cover most Compose hostname: translation cases while keeping the container name and guest hostname coupled. This PR keeps the explicit hostname-override path available for review, but it is not required for the alias PR.

Related to Compose compatibility work in Mcrich23/Container-Compose#119 and service/alias work in #1815/#1839.

Testing

• Tested locally
• Added/updated tests
• Added/updated docs

Checks run:

git diff --check origin/main..HEAD
swift test -c debug -Xswiftc -warnings-as-errors --filter 'ParserTest|UtilityTests'

The focused test run passed 122 tests after rebasing onto current origin/main and linked the CLI stack as part of the package test build.

Earlier manual smoke test against the normal running service:

.build/arm64-apple-macosx/debug/container run --rm --name codex-hostname-flag --hostname custom-host busybox hostname

The command printed:

custom-host

[jglogan]

@thromel The container --name is the hostname in container.

[thromel]

Thanks, that makes sense. I verified locally that container run --rm --name codex-name-hostname-check busybox hostname prints codex-name-hostname-check.

The gap I was trying to cover is Compose hostname:, where the requested guest hostname can be distinct from the container management name/service-derived ID. If container intentionally wants those to stay the same, then this PR is probably not the right direction and I can close it. If preserving that separation is acceptable, I can update the PR description/tests to make the distinction explicit.

[jglogan]

Let me think about this one. I'm not in love (right at this moment) with the idea of a hostname flag.

We could use the alias feature you propose to get Compose hostname working for all but seemingly perverse cases where someone puts hostname: existing-container-name in their YAML.

[thromel]

That matches the current split.

I updated this PR to make the hostname flag an optional/separate path rather than a prerequisite for Compose support. #1815 carries aliases as the primary path; aliases can represent most Compose hostname: cases while keeping the container management name and guest hostname coupled.

If keeping name and guest hostname coupled is the preferred API, this PR can be closed without blocking #1815/#1839.