feat: replace one playlist item in place

[rianjs]

Goal

Replace one playlist track at an exact position while preserving playlist order, completing the composable radio-edit-to-full-version workflow.

Depends on #24.

Surface

• sptfy playlists items update <playlist-reference> <zero-based-position> --item <track-reference>

Constraints

• update is the family-standard verb; do not add a radio-edit-specific or raw whole-playlist replacement command.
• Accept the established playlist and track reference forms and reuse the playlist-item read/add/remove paths.
• Re-read and validate the current item and snapshot at execution time. Reject non-track, local, unavailable, out-of-range, same-item, stale, and duplicate-source cases before mutation.
• Preserve order by adding the replacement at the target position before removing the unique original URI, passing the snapshot returned by the add into the removal.
• Prefer a recoverable partial failure: if removal fails after add succeeds, retain both tracks and report the exact playlist, position, old ID, and new ID needed for cleanup. Never lose the original silently.
• A successful result reports the position plus old/new IDs compactly and gives enough information to run the inverse update.
• Do not expose Spotify's raw whole-playlist uris replacement operation.
• Update the behavioral spec, README, and user smoke script for the completed workflow.

Empirical acceptance criteria

• Provider tests prove add-before-remove ordering, exact request bodies, snapshot handoff, and stop-on-failure behavior.
• Command tests prove replacement at start/middle/end, unchanged item count/order outside the target slot, URI/URL/raw-ID inputs, and compact stdout/stderr routing.
• Duplicate-source, same-item, stale/out-of-range, non-track/local/unavailable, invalid reference, and missing-scope cases fail before unintended mutation.
• A simulated second-step failure proves the original remains present and the recovery error contains only non-secret actionable identifiers.
• The opt-in live smoke composes playlist discovery, ordered item listing, candidate track selection, and items update; it verifies the exact replaced position and all neighboring IDs, then performs the inverse update and verifies exact restoration.
• The static live-smoke test covers success, inverse restoration, partial failure reporting, and cleanup failure.
• make check, make snapshot, and the opt-in replace-and-restore smoke pass.

[rianjs]

Implementation plan

Command and contract

• Add sptfy playlists items update <playlist-reference> <zero-based-position> --item <track-reference>.
• Validate the playlist reference, nonnegative position, required replacement reference, and flags before opening authentication.
• Require the existing two playlist-read and two playlist-modify scopes.
• Emit one compact success record on stdout only after both provider mutations succeed:
  updated<TAB>playlist-id<TAB>position<TAB>old-track-id<TAB>new-track-id<TAB>snapshot-id.
• Keep diagnostics and recovery guidance on stderr. The success record is directly invertible by running the same command at the reported position with the old track ID.

Use-case policy and dependency boundaries

• Add an update-specific narrow session capability/opener and construct it from the existing concrete session opener in the composition root; do not widen read/add/remove consumers.
• Keep Cobra responsible for parsing, opening the injected capability, calling the use case, classifying errors, and rendering. Put the replacement transaction in a directly testable use-case function.
• Read the playlist and complete ordered item list. Reject out-of-range, non-track/local/unavailable/future, same-item, duplicate source, and duplicate replacement IDs before mutation. Rejecting a preexisting replacement duplicate keeps the reported inverse operation safe under URI-only removal.
• Re-read item count and snapshot immediately before mutation; stale state fails without a write.
• Add the replacement at the target position first, then remove the unique original URI using the snapshot returned by add. Never expose Spotify's raw whole-playlist replacement endpoint.

Failure semantics

• A definite add rejection produces no mutation record.
• If add is outcome-uncertain, reuse the typed client uncertainty and return sanitized reconciliation guidance with playlist, position, old/new IDs; emit no stdout.
• If add succeeds and remove is definitely rejected, return a typed recoverable partial-replacement error stating that both tracks remain and carrying playlist, position, old/new IDs, and the add snapshot. Emit no success stdout and never imply that the original was lost.
• If removal is outcome-uncertain, return typed sanitized reconciliation guidance with the same identifiers and snapshot; emit no stdout because the final state is unknown.
• If final stdout writing fails after a confirmed replacement, preserve the full sanitized inverse record in the existing typed post-mutation output error.
• Mutation requests remain single-attempt.

TDD and verification

1. Add command/use-case tests first for raw ID, URI, and URL references; start/middle/end replacement; full-list pagination; exact unchanged neighbors/count; success output; scope and pre-auth validation; same-item, duplicate source/replacement, stale, out-of-range, and invalid item rejection.
2. Add provider/client/session tests proving POST-before-DELETE ordering, exact request bodies, position, add-snapshot handoff, stop-on-first failure, no retries, and typed uncertain outcomes.
3. Add focused tests for definite second-step partial failure, uncertain add/remove, safe error chains/messages, no misleading stdout, and failing final stdout.
4. Extend README and the behavioral contract with the command, inverse record, safety restrictions, and confirmed/partial/uncertain semantics.
5. Extend static and opt-in live smoke coverage to discover/list/select/update, assert the exact target and unchanged neighbors, run the inverse update, and prove exact baseline restoration. Cover partial and cleanup-failure behavior statically; live cleanup must tolerate Spotify's bounded write visibility delay.
6. Run focused tests during TDD, then make check, make snapshot, shell syntax/static smoke, live-tag compilation, and the authorized dedicated-playlist replace-and-restore probe when credentials are available. Restore the exact captured baseline before completion.

Out of scope

• Radio-edit-specific commands, bulk replacement, force-removing duplicate URIs, raw whole-playlist replacement, episodes/local items, automatic retry of ambiguous writes, and generalized workflow orchestration.