Add basecamp files replace: publish a new version of an uploaded file

[jeremy]

Closes#404 — the write half of the upload-versions story. #622's files versions reads the history; files replace <upload-id|url> <file> writes to
it, over SDK v0.14.0's UploadsService.CreateVersion: stage the file as an
attachment (the same two-step flow as uploads create), then POST it to the
upload's versions endpoint.

The upload keeps its id, URL and comments; the previous file becomes a past
version. That's the issue's use case verbatim: a release script ships each
build to the same published link instead of minting duplicates. (#404
proposed PUT-with-sgid on the upload itself — bc3 has since shipped the
dedicated versions endpoint, which is what this rides.)

Semantics follow the endpoint's presence rules:

• nobody is notified (no notify on the wire)
• the description carries forward unless --description is given; an
  explicit --description "" clears it (tri-state pinned by
  TestFilesReplaceDescriptionTriState, including that omission stays off
  the wire)
• --base-name renames without touching the extension
• alias: files new-version

Completeness bar: catalog action, API-COVERAGE row, SKILL.md examples +
semantics note, .surface regenerated (406 lines — command + alias across
the tree), unit tests (two-step flow order, URL acceptance, tri-state), a
real write smoke (files replace on the suite's own created upload, then
files versions asserting exactly one current) plus out-of-scope markers for
the alias leaves.

Live-verified against production: uploads create → files replace →
files versions shows both filenames with exactly one current: true, same
upload id throughout. Verification upload trashed after.

bin/ci green at the head (real exit 0).

---

Summary by cubic

Add basecamp files replace to publish a new version of an uploaded file while keeping the same upload ID/URL and comments. This delivers the write half of #404 and pairs with files versions to support stable links for new builds.

• New Features

  • Command: basecamp files replace <upload-id|url> <file> (alias: new-version) via SDK UploadsService.CreateVersion (stage attachment, then POST to versions).
  • Behavior: no notifications; description carries forward unless --description is set (empty clears); --base-name renames without changing the extension.
  • Accepts an upload ID or full Basecamp URL; returns the same upload with the new current version.
  • Updated command catalog/help; unit and e2e smoke tests; API coverage docs include replace.

• Bug Fixes

  • Pre-flight validation: reject URLs on untrusted hosts, URLs for a different account, non-positive upload IDs, wrong recording types, uploads collection/listing URLs (must target a single upload), and unresolved local images in --description before staging any data.
  • Breadcrumbs: reuse the caller’s reference; include --project with fallback to the root-level --project when the group flag is unset; shell-quote all embedded values (both files replace and files versions) so emitted commands are safe and round-trip through a shell.
  • Smoke test: read JSON from $output directly; tests pin --base-name presence/omission behavior.

^{Written for commit a0a5ec2. Summary will update on new commits.}

[Copilot]

Pull request overview

Adds files replace to publish new upload versions while preserving the upload’s identity and history.

Changes:

• Implements attachment staging and version creation with description and filename options.
• Adds unit and smoke coverage.
• Updates CLI metadata, documentation, API coverage, and surface snapshots.

Tip

If you aren't ready for review, convert to a draft PR.
Click "Convert to draft" or run gh pr ready --undo.
Click "Ready for review" or run gh pr ready to reengage.

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
internal/commands/files.go	Implements and registers files replace.
internal/commands/files_test.go	Tests replacement flow, URLs, and descriptions.
internal/commands/commands.go	Adds the catalog action.
e2e/smoke/smoke_files_write.bats	Adds the live replacement smoke test.
e2e/smoke/smoke_lifecycle.bats	Marks alias paths out of scope.
skills/basecamp/SKILL.md	Documents usage and semantics.
API-COVERAGE.md	Records endpoint coverage.
.surface	Regenerates the CLI surface snapshot.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit:fe92090ed7

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[Copilot]

Pull request overview

Copilot reviewed 8 out of 8 changed files in this pull request and generated no new comments.

Suppressed comments (1)

internal/commands/files.go:1755

• --project accepts project names, so interpolating it directly makes both breadcrumbs invalid for values such as "My Project" (--project My Project becomes two arguments). ref is also the original URL and may contain shell metacharacters such as &. Shell-quote both dynamic arguments, or construct the hints from resolved numeric IDs, before embedding them in copyable commands.

 ref := args[0]
scope := ""
if *project != "" {
scope = fmt.Sprintf(" --project %s", *project)

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit:3bf8723b01

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[Copilot]

Pull request overview

Copilot reviewed 8 out of 8 changed files in this pull request and generated 1 comment.

Suppressed comments (1)

internal/commands/files.go:1801

• Go %q is not shell escaping: unquoted project names can contain ;, $(), or backticks, and the double quotes used for whitespace still allow command substitution. Because these breadcrumbs are presented as copy-pasteable shell commands, always POSIX single-quote the project value (matching config.ShellQuote) rather than only checking for whitespace.

	if strings.ContainsAny(project, " \t") {
return fmt.Sprintf(" --project %q", project)
}
return " --project " + project

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit:99813373d4

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[jeremy]

Review-loop note, for the record: this was the third round on the same two
classes (breadcrumb quoting: missing scope → whitespace → metacharacters; URL
identity: account → path type). Per the working agreement, a third variation
means reassess the instrument rather than write the next selector — and the
reassessment concluded both classes close structurally in fe53313:

• Quoting is now an encoding, not an escape list. Every value embedded in
  breadcrumb text (the caller's reference and the project scope, in both
  replace and versions) passes through shellQuote: clearly-inert strings
  stay bare, everything else is single-quoted — the one POSIX form in which
  nothing substitutes. There is no remaining metacharacter dimension to find.
• A URL argument must identify an upload in the session's account. Account
  and path type are both validated before anything stages. Together they pin
  the URL to exactly the resource class this command mutates; there is no
  remaining URL dimension that can retarget it.

If a fourth variation of either class appears, it's evidence the closure
reasoning above is wrong somewhere — treat it as a bug in this note, not as
the next patch.

[Copilot]

Pull request overview

Copilot reviewed 8 out of 8 changed files in this pull request and generated 1 comment.

Suppressed comments (1)

internal/commands/files.go:1805

• The documented POSIX escape sequence is malformed: it ends with a curly double quote and does not match the '\'' sequence emitted below. Correct the example so future changes do not copy an invalid quoting form.

// spelled '\”. This is an encoding applied to every embedded value, not a

[Copilot]

Pull request overview

Copilot reviewed 8 out of 8 changed files in this pull request and generated no new comments.

Suppressed comments (2)

internal/commands/files.go:1812

• The documented POSIX representation for an embedded single quote is malformed here; it should match the '\'' sequence implemented below so this security-sensitive explanation remains accurate.

// spelled '\”. This is an encoding applied to every embedded value, not a

internal/commands/files.go:1739

• resolveLocalImages validates and uploads each image in one reverse-order pass. With a description such as a missing image followed by a valid local image, it uploads the valid image first and only then returns the local validation error, leaving staged data even though replacement never runs. This contradicts the preflight/no-request contract documented by this change. Validate every local image before uploading any of them (and add a mixed valid/missing regression case), then perform resolution.

 if descHTML, err = resolveLocalImages(cmd, app, descHTML); err != nil {

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit:cc7a0a094c

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[Copilot]

Pull request overview

Copilot reviewed 8 out of 8 changed files in this pull request and generated 1 comment.

Suppressed comments (1)

internal/commands/files.go:1812

• The documented POSIX single-quote escape is malformed; write \'\'' so the comment accurately matches the replacement performed below.

// spelled '\”. This is an encoding applied to every embedded value, not a

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit:16211fa680

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[Copilot]

Pull request overview

Copilot reviewed 9 out of 9 changed files in this pull request and generated no new comments.

Suppressed comments (1)

internal/commands/files.go:1822

• The shell-escaping example ends with a curly double quote and does not show the sequence that shellQuote actually emits. Correct it to '\'' so the helper's documentation accurately explains embedded single-quote handling.

// spelled '\”. This is an encoding applied to every embedded value, not a