--attach stack 5/8: Add the flag and upload behind it - #14181

Part of the pull request stack tracked in #14186.

Description

This is the fifth layer of the stack. The first commit adds the flag and reads its values. The second ties uploading to rewriting and decides when the resulting markdown is safe to write. No command offers the flag yet.

The flag is repeatable and takes a file path, optionally followed by # and alt text. Without alt text the file name is used. Every named file is validated before anything is uploaded.

Naming the same file twice is refused, and that includes a file and a symlink to it, and a file and a hard link to it, since both would upload the same bytes twice. An empty value is refused too, which is what a script produces when a variable is unset.

Conflicting flags are checked while the flag is being read, rather than in each command, so a command that offers the flag cannot forget to check them.

The flag is registered as a string array rather than a string slice, because a string slice splits on commas and a comma is legal in a file name:

cmd.Flags().StringArray(flagName, nil, "Attach an image or video `file`, in <file>#<alt text> format")

How did you test this change?

The whole stack was built and the failure path was exercised by hand against a private test repository. Three files were attached with the middle one made unreadable. Exactly one upload request left the machine for three attached files, the command exited non zero and named the file that failed, and the comment was still posted carrying the one file that did upload.

When the only attached file failed, nothing was posted at all and the command said so.

Duplicate detection was exercised with a plain duplicate, with a symlink to the same file, and with a hard link to it.

Key points

An upload cannot be undone and there is no endpoint to delete an uploaded asset. That single fact drives the design of the second commit.

The function reports how many assets reached the server, and a caller writes the body only when that count is above zero. Markdown that does not reference an uploaded asset would orphan that asset for good. A count of zero means nothing was uploaded, so nothing is lost by writing nothing.

Uploading stops at the first failure and nothing after it is attempted. A reference to a file that did not upload keeps its local path, so a partial failure leaves a body containing links that do not resolve. That is the accepted cost of writing a body that already carries a real uploaded asset, and it is a thing a user will see.

Notes for reviewers

The count returned by the upload function is the whole safety mechanism. Read that first, then read the callers in the layers above to see how it is used.

Authorship and follow-up

Who wrote this:

• A human wrote it.
• An agent wrote it under close human direction.
• An agent wrote it independently, and no human has guided the implementation beyond the initial prompt.

Who answers review comments:

• @BagToad will read and reply directly. Name the account.
• An agent will draft replies and @BagToad will read them before they are posted.
• Nobody has explicitly committed to replying.