feat(attachments): support uploading files on replies and thread creation

[scottlovegrove]

What

Ports the twist-cli file-attachment feature to comms-cli, using the attachments client added in @doist/comms-sdk 0.4.1.

tdc thread reply 12345 "See attached" --file ./diagram.png
tdc conversation reply 12345 "Photos" --file ./a.jpg --file ./b.jpg
tdc thread create CH123 "Release notes" --file ./report.pdf   # file-only, no body

How

• SDK bump @doist/comms-sdk 0.3.0 → 0.4.1.
• src/lib/local-file.ts — openLocalFileAsBlob resolves a path, verifies readability, returns a file-backed Blob; structured FILE_NOT_FOUND / FILE_READ_ERROR.
• src/lib/attachments.ts — uploadAttachments(files) validates every path before uploading any (no orphaned uploads), then uploads each concurrently (Promise.all, order preserved).
• --file is repeatable on thread reply, conversation reply, and thread create; a file-only post with no text is allowed (skips the editor prompt).
• conversation reply preflights the conversation (getConversation) before uploading so an invalid/forbidden target fails before orphaning an upload.
• --file + --close/--reopen on thread reply → CONFLICTING_OPTIONS.

Auth / scopes (403 handling)

Uploading needs the new attachments:write scope. attachments.upload gets a spinner entry so it routes through wrapResult; a token from before the scope change gets a 403 that's translated to INSUFFICIENT_SCOPE with the tdc auth login re-login prompt. Added attachments:read / attachments:write to the OAuth scope lists (read-write stays a superset of read-only).

Verification

• type-check, full suite (722 tests, incl. new local-file / attachments unit tests, --file suites for all three surfaces, and an attachments.upload 403 → INSUFFICIENT_SCOPE test), oxlint + oxfmt, and check:skill-sync all pass.

Mirrors Doist/twist-cli#260.

🤖 Generated with Claude Code

[doistbot]

Thanks scottlovegrove for your contribution 😇. The new file attachment feature integrates cleanly with the existing command structures and thoughtfully handles edge cases like preflighting conversations to prevent orphaned uploads.

Few things worth tightening:

• Restore type safety for thread replies by building a separately typed request object rather than casting the payload after the fact.
• Streamline file reads and uploads by using openAsBlob() directly instead of probing with an initial open/close, and cap the upload concurrency to prevent I/O spikes.
• Extend the permissions mock to ensure attachments.upload is properly tested through the mutating API path.

I also included a few optional follow-up notes in the details below.

Optional follow-up notes (4)

• [P3] src/commands/thread/create.ts:75: This new --file dry-run path never validates the local files. For example, tdc thread create CH100 "Title" --file ./missing.png --dry-run prints a preview here, but the real command fails with FILE_NOT_FOUND once it reaches uploadAttachments(). Please validate the file paths in dry-run as well (without uploading) so the preview matches actual execution; the same issue exists in the other new --file dry-runs.
• [P3] src/lib/options.ts:25: collect() is now a shared helper, but it only works if every caller remembers to pass [] as the Commander default. If a future repeatable option forgets that, previous is undefined and [...previous, value] throws at runtime. Make it defensive (previous: string[] = [] or previous ?? []) so the helper’s contract is enforced in code instead of comments.
• [P3] src/commands/conversation/conversation.test.ts:863: The PR description highlights that conversation reply preflights the conversation to prevent orphaned uploads on invalid targets. Consider adding a test where client.conversations.getConversation rejects (e.g., 404 Not Found) to verify that client.attachments.upload is indeed skipped.
• [P3] src/lib/local-file.test.ts:34: This only covers the FILE_NOT_FOUND branch. The helper also adds a separate FILE_READ_ERROR path for unreadable/non-file inputs, and that structured error is easy to lose without a test. Please add one deterministic non-ENOENT case here (for example a mocked EACCES/EPERM failure).

_{Share Feedback • Review Logs}

[doist-release-bot]

🎉 This PR is included in version 1.4.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀