feat(typefully): add comment-thread CRUD and comment marker handling instructions for draft updates

[rajatkapoor]

TL;DR

• New comments:* subcommands — list, create, reply, resolve, update, delete give the CLI full parity with the API's per-draft comment-thread endpoints, so agents can read and write reviewer feedback directly.
• Two new marker-handling flags on drafts:get / drafts:update — --exclude-comment-markers renders posts[*].text without <typ:comment-thread> markers (display-only), and --force-overwrite-comments deliberately drops threads on PATCH when the submitted text doesn't carry their markers.
• Strong agent guidance in SKILL.md so comments behave well: preserve every marker on PATCH, never resolve/delete a thread without explicit user instruction, after addressing a comment ask the user before resolving, and treat --force-overwrite-comments as a strict last resort. Self-closing markers are explicitly documented as paragraph anchors (not "empty" or "resolved" comments). Includes prose guidance to talk to users about comments, not the underlying marker tags.
• New tests — tests/comments.test.js covers all six new subcommands (success paths, missing-positional errors, query/body shape). tests/drafts.test.js adds four cases for the new marker flags (--exclude-comment-markers query string on GET/PATCH, --force-overwrite-comments alone vs. combined with --text).
• Changelog entry under Unreleased > Added documenting the new commands and flags for end users.

What's new

CLI (skills/typefully/scripts/typefully.js)

• comments:list <draft_id> — paginates comment-threads with optional --platform, --status, --limit, --offset.
• comments:create <draft_id> — creates a thread anchored on --selected-text at --post-index, with optional --platform / --occurrence.
• comments:reply <draft_id> <thread_id> — posts a reply on an existing thread.
• comments:resolve <draft_id> <thread_id> — resolves a thread (only after explicit user authorization, per skill guidance).
• comments:update <draft_id> <thread_id> <comment_id> — author-only edit of a comment's text.
• comments:delete <draft_id> <thread_id> [comment_id] — deletes either a single comment or the whole thread.
• drafts:get --exclude-comment-markers and drafts:update --exclude-comment-markers — render markers out of the response (display only; the response is not safe to PATCH back).
• drafts:update --force-overwrite-comments — sets force_overwrite_comments: true on the PATCH body so missing markers no longer trigger 409 COMMENTS_MARKER_MISMATCH. Skill guidance treats this as a last resort.
• New helpers: requireDraftIdPositional, requireThreadPositional, requireCommentPositional for consistent positional-argument error messages with usage hints.

Skill (skills/typefully/SKILL.md)

Reorganized "Comments on Drafts" into a single coherent flow, putting the mental model and core safety rules first:

1. Mental model — what markers are, span vs. self-closing/zero-width, with an explicit callout that self-closing markers anchor to the whole following paragraph and are not "empty" or "resolved" comments.
2. Core rules (3, numbered) — preserve every marker on PATCH; never resolve/delete without explicit user instruction; talk about comments, not markers.
3. Default edit workflow — GET → modify keeping markers → PATCH → ask the user, per addressed comment, whether to resolve.
4. Resolving and deleting: the ask-first rule — full list of "even when…" cases that do not authorize a resolve/delete.
5. Commands + technical notes (codepoint-equal selected_text, --occurrence, LinkedIn mention indivisibility, multi-platform --platform requirement, author-only comments:update).
6. Marker-handling flags — --exclude-comment-markers (display only) and --force-overwrite-comments (last resort with three explicit acceptable conditions).
7. How to talk about comments to the user — bad/good example pair so agents report "X post Add update instructions to Typefully skill #2 has 3 comments — one on …" instead of describing marker tag occurrences.
8. Quick reference table.

Changelog (skills/typefully/CHANGELOG.md)

Added entry under Unreleased > Added covering the new commands and flags.

Testing

• npx vitest run tests/comments.test.js tests/drafts.test.js — 61 tests pass (16 new comment-command tests + 4 new marker-flag tests + existing drafts coverage).
• All tests run against a hermetic local mock HTTP server (no network, no real Typefully API calls).

Notes

• No production-API behavior changes — only CLI commands, flags, and skill guidance.
• --force-overwrite-comments is intentionally surfaced but documented as a last resort to avoid accidental loss of reviewer comments during agent-driven edits.

[frankdilo]

looks good overall, left a couple minor comments

did not test the skill in actual use

[frankdilo]

wondering if this might confuse LLMs on LinkedIn posts that only have 1 post/atom, worth to test manually with the skill and see if worth chaning

[rajatkapoor]

Good catch. tried it and it made comment on the right word in the first shot

[rajatkapoor]

[frankdilo]

what does --use-defaults do here? not immediately clear

[rajatkapoor]

This is existing. It uses the social set that has been set as the default

[rajatkapoor]

It is an escape hatch in all commands that allows you to skip passing the social set id

[linuz90]

Left a couple of comments

[linuz90]

@rajatkapoor why commenting this?

[linuz90]

This whole section seems too big and verbose to me. The point of including a CLI in this skill is to avoid teaching LLMs about the underlying API, or at least not extensively. I'm pretty confident this part could be half as long and still achieve the same goal of enabling agents to handle comments with the skill.