Add and change cloud files and Google documents in Docs & Files

JE
18m ago
+2600-5

Why

The gap card 10476950575 names four SDK operations the CLI doesn't reach: adding and changing cloud files and Google documents in Docs & Files. files show already reads both kinds; nothing could create or edit them.

What changed

OperationCommand
CreateCloudFilebasecamp files cloud-files create [title] --url … [--service] [--description] [--subscribe|--no-subscribe] [--visible-to-clients]
UpdateCloudFilebasecamp files cloud-files update <id|url> [--url] [--title] [--service] [--description]
CreateGoogleDocumentbasecamp files google-docs create [title] --url … [--type] [--description] [--draft] [--subscribe|--no-subscribe] [--visible-to-clients]
UpdateGoogleDocumentbasecamp files google-docs update <id|url> [--url] [--title] [--type] [--description] [--publish] [--subscribe|--no-subscribe]

The groups hang off files, so they appear under its aliases too (docs, vaults, …), like files documents and files folders.

  • Update is a full replace in Basecamp. Both controllers build a new recordable from the permitted params alone, so an omitted title or description is erased. The update commands read the record first and send back every field no flag changes. The description goes back verbatim, as files update already does for documents. The known rich-text write-back problem with @mentions is card 10439714339.
  • --service is inferred from the URL's host with the same table doors uses, falling back to other. --type is inferred from a docs.google.com path (document, spreadsheets, presentation), falling back to other. An explicit flag wins. On update, a new URL changes the service or type only when its host or path names one.
  • Google documents publish on create unless --draft is given, matching files documents create; Basecamp's own default is a draft. On update, status is left out unless --publish is given, so Basecamp keeps the document's current status. --publish=false is refused, because a published document can't go back to a draft.
  • files show breadcrumbs for a cloud file or Google document now point at these update commands, not at files update, which can't change them.

Builds on

main at 29150b2, which already pins SDK v0.35.0, with main merged in through da36c00. No bump is needed.

Left out

  • --subscribe on cloud-files update. bc3 applies subscriptions on update only to a drafted recording (Recording::DraftSubscribers), and CloudFilesController always creates and updates a cloud file as active. The flag would be a no-op. On google-docs update it is offered and documented as affecting drafts only.
  • Subscriptions on files upload. The card also asks for upload notifications. CreateUpload is already reached, but files upload still sends no subscriber list. That part of the card is untouched, so the card stays open for it.

Tests

  • Unit tests in internal/commands/files_links_test.go cover:
    • inference of the service and type;
    • subscribers sent, [] for --no-subscribe, and none by default;
    • refusals before any request;
    • update sending back unchanged fields;
    • an empty --description clearing it;
    • draft and publish;
    • an explicit --type winning over the URL.
  • e2e validation in e2e/files.bats: create without --url, update with no fields, an unknown --type.
  • Smoke: e2e/smoke/smoke_file_links.bats creates and renames one of each against the QA project. The docs and vaults variants are marked out of scope in smoke_lifecycle.bats, as for the other files subgroups. check-smoke-coverage accounts for every leaf.
  • API-COVERAGE.md gains cloud_files and google_documents rows (232 of 232 tracked), and .surface is regenerated.
  • bin/ci passes locally on the merge with main through da36c00. TestHardenConfigDir in internal/cli (untouched here) fails under a umask of 077, because its fixtures are created without an explicit chmod and it expects 0755 and 0644; it passes under 022, as in CI.

Gap card

https://app.basecamp.com/2914079/buckets/48521764/card_tables/cards/10476950575

Summary by cubic

Adds files cloud-files create/update and files google-docs create/update, so the CLI can now add and change cloud files and Google documents in Docs & Files; previously files show could only read them.

  • Updates replace the whole record in Basecamp, so the update commands read the record first and send back every field no flag changes; an explicitly empty --description clears it.
  • Update accepts a URL only from a trusted Basecamp host naming one record of its own type in the configured account, as doors does; descriptions upload the local images they name.
  • --service is inferred from the URL host and --type from a docs.google.com path, with an explicit flag winning.
  • Google documents publish on create unless --draft is given; on update, status is untouched unless --publish.
  • files show breadcrumbs for these records now point at the new update commands, naming the ID create prints since files list doesn't list them; follow-up commands carry the profile and account.
  • --subscribe is omitted from cloud-files update because Basecamp only applies subscriptions to drafted records, and cloud files are always active; on google-docs update it affects drafts only.
  • Subscriptions on files upload are still unsupported, so the gap card stays open for that.