feat: --out for binary payloads — media-stream download on get, base64 decode on action

[igor-ctrl]

Summary

--out means "write the payload to this path instead of stdout". It lands on two commands, because BC hands back binary two different ways and until now neither reached a file.

• bcli get <endpoint> <record-id> --out invoice.pdf — BC advertises a record's binary attachment as a <field>@odata.mediaReadLink annotation. The record is read, the link it advertises is streamed to disk.
• bcli action <endpoint> <key> <name> --out doc.pdf — a bound action returns its payload as base64 in the response's value property. That gets decoded and written.

The use case is the ordinary one: a posted purchase invoice has a scanned PDF attached to it, someone needs the PDF, and the only way to get it was to read the record, find the media link by hand, and curl it with a token you had to mint yourself.

SDK side: AsyncBCClient.get_media / BCClient.get_media over a new BCTransport.download.

Closes the client half of the installer repo's issue #21.

Design decisions

The media GET honours disable_standard_api. get_media resolves the record through the same _resolve_url every other read uses, so the endpoint registry, an explicit --publisher/--group/--version, and the lockdown flag all apply to a media download exactly as they apply to bcli get. A profile that can't read an entity can't download its attachments either — a media stream is not a side door around the allowlist.

The media link is re-validated as a BC origin. Unlike every other URL bcli builds, this one comes out of a response body. A tampered or compromised endpoint returning content@odata.mediaReadLink: https://attacker.example/leak would otherwise receive the bearer token. download calls assert_bc_origin first, same guard as get_absolute on @odata.nextLink.

download is a sibling of _request, not a branch inside it. _request buffers the response and calls response.json() on success — wrong for every byte of a PDF. The new loop mirrors it exactly on retry policy, error mapping, and structured logging, and differs only in body handling. A GET is always retry-safe, so it needs no retry_safe gate.

Temp file + truncate-per-attempt. One .part file is opened before the retry loop and seek(0); truncate() runs at the top of every attempt, then os.replace moves it onto the destination only on success. Without the truncate, a retry following a half-streamed response appends the second body to the first half of the first — a corrupt file that nothing in the output ever mentions. This matters more since 0.7.0 stopped absorbing transient 5xx on writes: a visible retry has to be exactly right about bytes. No .part survives any failure path, and a failed download never leaves a truncated file where a complete one is expected.

Overwrite refusal is the default. An existing file is never replaced without --overwrite, and a missing parent directory is an error rather than an mkdir — matching bcli extract's _check_writeable precedent. Both checks run before any network round trip. On action that ordering is load-bearing: the POST can change BC, so an unwritable destination has to fail before the server is touched, not after.

--media auto-discovery, and when it refuses. With no --media, the record's @odata.mediaReadLink annotations are scanned; exactly one is downloaded. Zero or several raise an error naming what was found, because writing whichever came first would be a silent guess into the user's file. --media <field> names one explicitly and also composes the conventional <record-url>/<field> sub-resource for pages that serve a media property without annotating it. The field name is validated as a single URL path component, so it can't retarget the request.

--out vs --result-out on action. They write different things — decoded payload bytes vs the JSON envelope describing the invocation — and the help text says so, at length, because "write the output to a file" describes both and an agent picking the wrong one gets no signal that it did. They compose. A 204 No Content reports that there was no payload rather than writing a zero-byte file that looks identical to a successful download, and decoding happens before emit_success, so an undecodable response is recorded as failed.

get stays a read. No SafeContext, no confirm_write_or_exit, READ_PATHS unchanged. Nothing is written to BC.

Also promotes four helpers to the public API — bcli.odata.{extract_field_references, suggest_field, validate_filter_fields} and bcli.registry.import_from_metadata. Downstream saved-query catalog validation needs them and was reaching into _filter_fields / _importers directly, which we couldn't have changed without silently breaking it. Same reasoning as the bcli.queries extraction in 0.7.0.

Notes

• The new flags auto-propagate into the MCP tools. bc_get and bc_action are generated from describe, so --out/--media/--overwrite appear there without any change to bcli_mcp — a describe test now pins that. Worth stating plainly: file writes land on the MCP host, i.e. the user's own machine, not on a server.
• action --out has not been exercised live. There is no server-side action returning a base64 payload to point it at yet; its coverage is unit tests only. get --out was verified against a real tenant (read-only).
• Downloaded files inherit the temp file's 0600 mode rather than the umask, on the grounds that a downloaded invoice is the account's data.
• Version bumped to 0.8.0 with a CHANGELOG entry. src/bcli/_version.py untouched — it reads from package metadata.

Test plan

• ruff check src/ tests/ clean
• Full suite: 1142 passed, 5 skipped (up from 1092; +50 new)
• Transport/SDK: happy path with request order + Accept: */* + auth header; zero/two media fields; explicit field with and without an annotation; ../evil field rejected before any HTTP; off-origin mediaReadLink rejected with the media URL never requested; retry after 503 and after a mid-stream ReadTimeout both yield the body exactly once with no .part left; 404 leaves no file and no litter; sync wrapper delegates
• get CLI: forwarding of every argument; --media without --out; --out without a record id; all eight query flags and an explicit --format conflict with get_media never awaited; existing file refused then accepted with --overwrite; missing parent dir not created; --dry-run writes nothing and calls nothing
• action CLI: base64 decoded with no base64 on stdout; 204 fails and marks the envelope failed; dict without value lists the keys; invalid base64 fails; existing file refused with post.await_count == 0; --out and --result-out both written
• describe pins --out/--media on get
• Live read-only smoke against a real tenant: downloaded a 36,933-byte PDF (%PDF magic bytes confirmed), re-run refused with exit 1, --overwrite succeeded, a record with no media property produced the clean "no media stream" error with no file created, --dry-run wrote nothing, conflicting flags rejected, bcli describe -f json shows the three new options
• action --out against a live action returning base64 — deferred until such an action exists server-side