feat: add and remove playlist items by position

[rianjs]

Goal

Ship the first reversible playlist mutation slice: insert tracks while preserving order and remove one exact playlist position, with live provider-contract checks and automatic fixture restoration.

Depends on #23.

Surface

• sptfy playlists items add <playlist-reference> <track-reference>... [--position <n>]
• sptfy playlists items remove <playlist-reference> <zero-based-position>

Constraints

• Request the sorted public/private playlist modification scopes only when these mutations ship; stale credentials fail before mutation with the established sptfy init --overwrite hint.
• Add accepts validated track IDs, typed track URIs, and canonical track URLs. It validates the complete batch before I/O, preserves input order and intentional duplicates, inserts at the zero-based position, and appends when --position is omitted.
• Use Spotify's current POST /playlists/{id}/items and DELETE /playlists/{id}/items endpoints, not deprecated /tracks endpoints.
• Chunk adds at Spotify's 100-item boundary without changing requested order or insertion position.
• Remove identifies the current track at the requested position, uses the current snapshot, and removes it only when that source URI occurs once. If it occurs more than once, fail before mutation rather than letting Spotify remove every occurrence.
• Reject non-track, local, unavailable, out-of-range, and stale-position cases without guessing.
• Mutations remain unprompted because their successful output retains enough identity/position information for the inverse command. Emit compact success data only after every required request succeeds.
• The live harness must restore the exact original playlist order on success, failure, interrupt, and cleanup failure paths.

Empirical acceptance criteria

• A live provider-contract check demonstrates Spotify's actual URI-removal behavior for duplicate occurrences before the CLI relies on the uniqueness guard.
• Provider tests prove exact methods/paths/bodies, snapshot propagation, append and positioned insert behavior, and 100/101 add chunking.
• Command tests prove add-at-start/middle/end, append, duplicate preservation, exact unique-position removal, and inverse-command output.
• Duplicate-source removal, stale/out-of-range positions, invalid references, missing scopes, and complete-batch validation failures make no unintended mutation request.
• The opt-in live smoke inserts a known track at a known position, verifies the exact resulting order, removes that exact position, and verifies byte-for-byte restoration of the original ordered IDs.
• Static live-smoke tests prove cleanup runs and restoration failures fail the smoke.
• make check, make snapshot, and the opt-in add/remove round trip pass with the fixture restored.

[rianjs]

Issue #24 plan — add and remove playlist items by position

Outcome and public contract

Ship the first reversible playlist-mutation slice without adding a workflow command or speculative abstraction:

• sptfy playlists items add <playlist-reference> <track-reference>... [--position <n>]
• sptfy playlists items remove <playlist-reference> <zero-based-position>

All references use the existing strict Spotify ID/URI/canonical-URL parser. Add validates the complete batch before opening a session, preserves argument order and intentional duplicates, appends when --position is absent, and accepts explicit positions from zero through the current item count. Remove accepts exactly one nonnegative absolute position.

Successful stdout is a compact, headerless tab record; stderr remains for diagnostics only:

• add: added<TAB><playlist-id><TAB><start-position><TAB><count><TAB><final-snapshot-id>
• remove: removed<TAB><playlist-id><TAB><position><TAB><track-id><TAB><final-snapshot-id>

The add record can be inverted by removing count times at start-position; the remove record can be inverted by adding track-id at position. No success record is written until every required mutation request succeeds.

Implementation

1. Authorization and composition boundary

   • Add playlist-modify-private and playlist-modify-public constants to the sorted OAuth scope set, update authorization/token/init expectations, and document that existing credentials require sptfy init --overwrite.
   • Let playlist reads keep their two read-scope guard; require both read scopes and both modification scopes for add/remove before any Spotify resource request.
   • Extend the existing narrow playlist Session interface and concrete session with only the typed add/remove capabilities. Continue constructing the concrete session in root.New; add no service locator or package-global client.

2. Typed current-endpoint client operations

   • Add JSON-body request support for fixed-origin requests and set Content-Type: application/json.
   • Add a typed POST /playlists/{id}/items operation accepting 1–100 canonical track URIs and an optional nonnegative position; validate the request and the nonempty snapshot response.
   • Add a typed DELETE /playlists/{id}/items operation for one canonical track URI plus a nonempty snapshot, using the current items body member (never deprecated /tracks or tracks). Validate the returned snapshot.
   • Do not automatically replay playlist mutation requests after an ambiguous provider failure; a POST retry could duplicate an insertion.

3. Add orchestration

   • Parse and validate every track reference before I/O without deduplicating.
   • Read playlist detail once to obtain the current total and validate the requested insertion point; for append, report the current total as the start position.
   • Chunk at 100. Omitted-position chunks remain appends. Explicit-position chunks use position + chunkStart, preserving order across 100/101 boundaries.
   • Carry each returned snapshot forward only as result state and emit one final record after all chunks succeed.

4. Exact-position remove orchestration

   • Read playlist detail and its snapshot, then enumerate all playlist items through the existing fixed-origin paginated client, requiring page totals to agree with the detail count.
   • Resolve the requested absolute position. Reject out-of-range, unavailable, local, episode, unknown/future, or otherwise non-track targets.
   • Count the target track ID across the complete playlist. If its canonical source URI occurs more than once, fail before DELETE; current Spotify removal is URI-based and does not expose a position field.
   • Re-read playlist detail immediately before mutation and require the snapshot and item count to match the preflight values. A changed snapshot is a stale-position failure with no DELETE request.
   • Delete the unique canonical track URI against the verified snapshot and emit the removed track ID/position only after success.

5. Output and documentation

   • Add the two mutation records to the output contract with cell sanitization where applicable, keeping logs/errors on stderr.
   • Promote add/remove from future boundaries into the implemented surface and document reference forms, zero-based semantics, duplicate behavior, chunking, scopes, current endpoints, reversibility, and the unavoidable possibility that an earlier add chunk succeeded if a later chunk fails.

Tests and empirical gate

• Client tests assert exact method, fixed /items path, JSON body/member names, content type, optional position, snapshot propagation/validation, request bounds, and no mutation retry. They explicitly reject deprecated /tracks/tracks shapes.
• Command tests cover add at start/middle/end, append, input-order and duplicate preservation, 100/101 chunking, complete-batch validation before session open, scope failures before resource I/O, exact unique-position removal, inverse records, full-list duplicate detection, stale snapshot/count, out-of-range and non-track positions, and stdout suppression on failure.
• Session/root tests prove constructor wiring and delegation without moving orchestration into the composition root.
• The opt-in provider-contract check temporarily creates duplicate occurrences of a dedicated non-baseline track, demonstrates that one current URI-removal request removes every occurrence, and restores the exact baseline in cleanup. The command live smoke then inserts one known track at a known middle position, verifies the complete ordered IDs, removes that exact position, and verifies byte-for-byte baseline restoration.
• Static smoke tests exercise success, failure, interrupt/cleanup entry points, and restoration failure. Cleanup must fail the smoke if exact restoration cannot be proven.
• Required gates: focused tests, make check, make snapshot, static live smoke, real provider-contract evidence, and the opt-in add/remove round trip with the fixture restored.

Non-goals

• No episodes, local items, batch positional removal, force-removal of duplicate URIs, whole-playlist replace, reorder, interactive confirmation, or high-level “replace track” workflow; feat: replace one playlist item in place #25 composes this slice.
• No JSON resource output and no new dependency.