click 8.4.2: Render optional subcommand brackets [COMMAND] in help usage synopsis when invoke_without_command is True

# CodeSampleX Notes: click Group invoke_without_command Usage Synopsis

## search_known_solution Result
`search_known_solution` answered with existing sample `sha256:02f8c2f7fe825dcfb2135cbd593f008e36f7550ce68c3fcfa7c6de1bcfcbb02f` ("Test a click command without spawning a subprocess").

## What a Model Would Have Written Instead
A model would write help-text assertions expecting `Usage: <prog> [OPTIONS] COMMAND [ARGS]...` for all groups, unaware that `invoke_without_command=True` changes the synopsis from mandatory `COMMAND` to optional `[COMMAND]`.

## How the Wrong Version Fails
On Click <= 8.4.1, the contract fails loudly with an `AssertionError` because `Group.format_usage()` formatted subcommands as mandatory `COMMAND` even when `invoke_without_command=True` was set.

{"case":{"caseId":"case:sha256:ba26869568c58adf0240cbd28d8253f98383f2029b2443011f0847722096c819","contract":["assert a Group with invoke_without_command=True renders [COMMAND] as optional in its usage help synopsis","assert a standard Group with invoke_without_command=False renders COMMAND as required in its usage help synopsis","assert invoke_without_command=True executes the root group callback when invoked without subcommands","assert invoke_without_command=False exits with usage error code 2 when invoked without subcommands"],"goal":"Render optional subcommand brackets [COMMAND] in help usage synopsis when invoke_without_command is True","kind":"HOW","packages":["pkg:pypi/click@8.4.2"],"schemaVersion":1,"symbols":["click.group","click.Group","click.testing.CliRunner"]},"contractCommand":["python","test/contract.py"],"environment":{"arch":"x64","ecosystem":"pypi","executionContext":"python","language":"python","os":"linux","packageManager":"pip","runtime":"python","schemaVersion":1},"license":"MIT-0","packages":["pkg:pypi/click@8.4.2"],"schemaVersion":1,"symbols":["click.group","click.Group","click.testing.CliRunner"],"verifierAdapter":"python@1"}

click==8.4.2

"""Click sample package."""

"""Click CLI demonstrating group usage synopsis formatting and invocation semantics."""

import click


@click.group(invoke_without_command=True)
@click.option("--version", is_flag=True, help="Show the tool version.")
@click.pass_context
def standalone_cli(ctx: click.Context, version: bool) -> None:
    """A root CLI group configured with invoke_without_command=True."""
    if ctx.invoked_subcommand is None:
        if version:
            click.echo("standalone_cli 1.0.0")
        else:
            click.echo("standalone_cli: running default action")


@standalone_cli.command("status")
def standalone_status() -> None:
    """Check service status."""
    click.echo("status: all systems normal")


@click.group(invoke_without_command=False)
def strict_cli() -> None:
    """A standard root CLI group requiring an explicit subcommand."""
    pass


@strict_cli.command("status")
def strict_status() -> None:
    """Check service status."""
    click.echo("status: all systems normal")

"""Contract verifying Click 8.4.2's fix for Group usage synopsis with invoke_without_command=True."""

import os
import sys

sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
from click.testing import CliRunner

from src.cli import standalone_cli, strict_cli

runner = CliRunner()

# 1. Click 8.4.2 fix (#3059 / #3507): A Group with invoke_without_command=True
# marks its subcommand as optional in the usage help, rendering '[COMMAND]'
# instead of 'COMMAND'.
help_standalone = runner.invoke(standalone_cli, ["--help"])
assert help_standalone.exit_code == 0, help_standalone.output
usage_standalone = help_standalone.output.strip().splitlines()[0]
assert usage_standalone == "Usage: standalone-cli [OPTIONS] [COMMAND] [ARGS]...", (
    f"Expected '[COMMAND]' indicating optional subcommand, got: {usage_standalone!r}"
)

# 2. Standard Group with invoke_without_command=False retains mandatory 'COMMAND' in synopsis.
help_strict = runner.invoke(strict_cli, ["--help"])
assert help_strict.exit_code == 0, help_strict.output
usage_strict = help_strict.output.strip().splitlines()[0]
assert usage_strict == "Usage: strict-cli [OPTIONS] COMMAND [ARGS]...", (
    f"Expected 'COMMAND' indicating required subcommand, got: {usage_strict!r}"
)

# 3. Invoking the standalone group without any subcommand runs the root callback directly.
result_default = runner.invoke(standalone_cli, [])
assert result_default.exit_code == 0, result_default.output
assert result_default.output.strip() == "standalone_cli: running default action"

result_version = runner.invoke(standalone_cli, ["--version"])
assert result_version.exit_code == 0, result_version.output
assert result_version.output.strip() == "standalone_cli 1.0.0"

# 4. Invoking the subcommand works as expected.
result_sub = runner.invoke(standalone_cli, ["status"])
assert result_sub.exit_code == 0, result_sub.output
assert result_sub.output.strip() == "status: all systems normal"

# 5. Invoking the strict group without subcommand exits with code 2 (usage error).
result_strict_missing = runner.invoke(strict_cli, [])
assert result_strict_missing.exit_code == 2, result_strict_missing.output
assert "Usage: strict-cli [OPTIONS] COMMAND [ARGS]..." in result_strict_missing.output

print("CONTRACT PASS: click 8.4.2 correctly renders [COMMAND] for invoke_without_command=True groups and executes root callback")