feat: list ordered playlist items

[rianjs]

Goal

List a playlist's contents in stable order with the positional information required by later exact mutations.

Depends on #22.

Surface

• sptfy playlists items list <playlist-reference>
• Supports -m/--max (1-50), --next-page-token, --id, --extended, --fields, and --include-artwork.

Constraints

• Use Spotify's current GET /playlists/{id}/items endpoint, not the deprecated /tracks surface.
• Output always has an absolute zero-based POSITION in its normal shape and an explicit TYPE; track rows retain artist and album breadcrumbs.
• Safely represent episode, local, unavailable/null, and future unknown item shapes without panics or fabricated track metadata. Mutation support remains track-only until separately shipped.
• Render the playlist parent identity once rather than repeating playlist metadata in each row.
• --id remains pure item IDs. Other shape flags follow existing precedence and text-only rules.
• Bind opaque continuation tokens to the playlist-items surface and parsed playlist ID; never follow provider URLs.
• Preserve provider order exactly and validate page metadata before rendering.
• Update the behavioral spec, README, and smoke documentation only for this shipped surface.

Empirical acceptance criteria

• Provider tests prove the exact request path, 1/50 bounds, offsets, fixed origin, response validation, and no provider-pagination following.
• Command tests cover absolute positions across resumed pages, track breadcrumbs, each non-track/null/local shape, empty pages, shape flags, and parent rendering.
• Wrong-kind references, malformed or cross-playlist tokens, unknown fields, and invalid bounds fail before unintended provider requests.
• The opt-in live smoke lists a dedicated playlist fixture with at least three ordered items, proves positions match Spotify's actual order, and proves continuation resumes at the correct absolute position.
• The static live-smoke test exercises the same assertions without network access.
• make check, make snapshot, and the opt-in ordered-items smoke pass.

[rianjs]

Plan — Issue #23: List ordered playlist items

Intent and fixed decisions

• Ship only sptfy playlists items list <playlist-reference>; playlist mutations remain out of scope.
• Use Spotify's current GET /playlists/{id}/items endpoint with additional_types=episode; never call the removed /tracks endpoint or decode the deprecated track member.
• Reuse the playlist read scopes from feat: discover current user's playlists #22. Add no OAuth scopes and no dependencies.
• Preserve response order and compute each row's absolute zero-based POSITION as page offset + row index.
• Render Playlist ID: <id> once before normal tables. --id remains pure IDs and therefore has no parent line; entries without a Spotify ID are omitted from ID-only output.

Output contract

Default table:

POSITION | TYPE | ID | ITEM | ARTIST_IDS | ARTISTS | ALBUM_ID | ALBUM | DURATION

• TYPE is track, episode, local, or unavailable for the known wrapper shapes. A future provider type is preserved in sanitized form; a non-null item without a type renders unknown.
• Track rows populate artist and album breadcrumbs. Episode, local, unavailable, and unknown rows leave inapplicable cells as -; no track metadata is fabricated.
• --extended adds URI | URL | ADDED_AT | ADDED_BY_ID | DISC_NUMBER | TRACK_NUMBER | EXPLICIT | RESTRICTION.
• --include-artwork adds ARTWORK, using album artwork for tracks and item artwork for episodes when available.
• --fields replaces the selected columns with the existing case-insensitive/deduplicating precedence; --id overrides every other shape flag.

Implementation steps

1. Add a minimal flattened playlist-item/page model and current-schema decoder in internal/client. Decode the item raw payload by its type so null, local, episode, and unknown future shapes remain representable without a speculative union framework.
2. Add fixed-origin ListPlaylistItems(ctx, playlistID, limit, offset) using /playlists/{id}/items?additional_types=episode&limit=…&offset=…. Validate playlist IDs, 1–50 limits, offsets, exact page metadata, required arrays, totals, nonnegative durations, and any present Spotify item IDs before returning; never follow provider next URLs.
3. Add playlist-item field selection and rendering in internal/output, reusing existing cell sanitization, duration, artist, and artwork helpers.
4. Extend the existing constructor-injected playlist command/session capability with an items group and list command. Bind opaque tokens to playlist-items:<playlist-id>, validate references/fields/bounds/tokens before opening a session, enforce the existing playlist read scopes, and route data to stdout with continuation hints on stderr.
5. Wire the new session method through the existing root composition and add one real-session/root-path test; do not add a parallel command framework.
6. Extend README, behavioral spec, and the static/opt-in live smoke only for the shipped read surface.

TDD and empirical verification

• Provider tests: exact current request path/query, raw/URI/URL parent references, 1/50 bounds, resumed offsets, fixed origin, hostile next ignored, malformed metadata, current item payload, and track/episode/local/null/unknown decoding.
• Command/output tests: absolute positions on first/resumed pages; exact parent/default/selected/extended/artwork/ID-only/empty output; track breadcrumbs; every non-track shape; sanitization; stdout/stderr; wrong-kind references; malformed/cross-surface/cross-playlist tokens; invalid fields/bounds before session/provider work.
• Root/session tests: authenticated composition reaches the exact provider path and renders the stable contract.
• Live fixture: require SPOTIFY_CLI_LIVE_PLAYLIST_ITEM_IDS with at least three expected ordered IDs alongside SPOTIFY_CLI_LIVE_PLAYLIST_ID. Prove the first page's IDs/positions, continuation at the next absolute position, and equivalence with ID-only order. Mirror the assertions in the no-network fake harness.
• Gates: focused tests, make check, make snapshot, and real make live-smoke; final diff audit confirms no mutation commands/scopes or deprecated playlist API surface.

Ponytail boundary

• Keep one flattened row DTO and one renderer because the command needs a mixed ordered table, not a reusable polymorphic media hierarchy.
• Do not add episode catalog commands, show breadcrumbs, mutation helpers, raw-output modes, or generalized pagination/command frameworks.