feat(spotify): add Spotify playback adapter (#560)

* feat(spotify): add Spotify playback adapter

Adds a new adapter for controlling Spotify via the official Web API.
Uses Strategy.PUBLIC with OAuth2 — no browser session required.

Commands: auth, status, play, pause, next, prev, volume, search, queue, shuffle, repeat.
Credentials are loaded from ~/.opencli/spotify.env or environment variables.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* fix(spotify): rename index.ts → spotify.ts and fix CliError calls

- Renamed src/clis/spotify/index.ts to spotify.ts so the build-manifest
  picks it up (index.js is intentionally excluded from manifest scanning)
- Fixed 4 CliError calls: constructor now requires (code, message, hint?)
  so each throw now passes an appropriate error code as first argument

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* fix(spotify): fix token refresh corruption, env parse, null guards, validation

- refreshAccessToken: check res.ok before parsing; construct Tokens object
  directly instead of mutating loadTokens() result to avoid writing
  undefined/NaN on Spotify error responses; preserve existing refresh_token
  when Spotify omits it from the response
- loadEnv: split on first '=' only so values containing '=' are preserved
- SCOPES: remove write/library/top scopes not used by any command
- status: guard against data.item being null (active device but no track)
- volume: validate 0-100 range before API call
- auth: check tokenRes.ok on initial token exchange; add server.on('error')
  handler for EADDRINUSE; add 5-minute timeout with clearTimeout on close

* feat(postinstall): auto-create ~/.opencli/spotify.env template on install

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* fix(spotify): guard null progress, podcast items, missing tracks data, corrupted tokens, invalid search limit

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* fix(spotify): improve missing credentials error with step-by-step guidance

* fix(spotify): harden setup and add docs coverage

---------

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-authored-by: jackwener <jakevingoo@gmail.com>

Author: 3 people

README.md

@@ -121,6 +121,7 @@ git clone git@github.com:jackwener/opencli.git && cd opencli && npm install && n
 | **bilibili** | `hot` `search` `history` `feed` `ranking` `download` `comments` `dynamic` `favorite` `following` `me` `subtitle` `user-videos` |
 | **twitter** | `trending` `search` `timeline` `bookmarks` `post` `download` `profile` `article` `like` `likes` `notifications` `reply` `reply-dm` `thread` `follow` `unfollow` `followers` `following` `block` `unblock` `bookmark` `unbookmark` `delete` `hide-reply` `accept` |
 | **reddit** | `hot` `frontpage` `popular` `search` `subreddit` `user` `user-posts` `user-comments` `read` `save` `saved` `subscribe` `upvote` `upvoted` `comment` |
+| **spotify** | `auth` `status` `play` `pause` `next` `prev` `volume` `search` `queue` `shuffle` `repeat` |
 
 66+ adapters in total — **[→ see all supported sites & commands](./docs/adapters/index.md)**
 

README.zh-CN.md

@@ -173,6 +173,7 @@ npm install -g @jackwener/opencli@latest
 | **douban** | `search` `top250` `subject` `photos` `download` `marks` `reviews` `movie-hot` `book-hot` | 浏览器 |
 | **facebook** | `feed` `profile` `search` `friends` `groups` `events` `notifications` `memories` `add-friend` `join-group` | 浏览器 |
 | **google** | `news` `search` `suggest` `trends` | 公开 |
+| **spotify** | `auth` `status` `play` `pause` `next` `prev` `volume` `search` `queue` `shuffle` `repeat` | OAuth API |
 | **36kr** | `news` `hot` `search` `article` | 公开 / 浏览器 |
 | **imdb** | `search` `title` `top` `trending` `person` `reviews` | 公开 |
 | **producthunt** | `posts` `today` `hot` `browse` | 公开 / 浏览器 |

docs/.vitepress/config.mts

@@ -105,6 +105,7 @@ export default defineConfig({
                 { text: 'Barchart', link: '/adapters/browser/barchart' },
                 { text: 'Hugging Face', link: '/adapters/browser/hf' },
                 { text: 'Sina Finance', link: '/adapters/browser/sinafinance' },
+                { text: 'Spotify', link: '/adapters/browser/spotify' },
                 { text: 'Stack Overflow', link: '/adapters/browser/stackoverflow' },
                 { text: 'Wikipedia', link: '/adapters/browser/wikipedia' },
                 { text: 'Lobsters', link: '/adapters/browser/lobsters' },

docs/adapters/browser/spotify.md

@@ -0,0 +1,62 @@
+# Spotify
+
+**Mode**: 🔑 OAuth API · **Domains**: `accounts.spotify.com`, `api.spotify.com`
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `opencli spotify auth` | Authenticate with Spotify and store tokens locally |
+| `opencli spotify status` | Show current playback status |
+| `opencli spotify play [query]` | Resume playback or search-and-play a track |
+| `opencli spotify pause` | Pause playback |
+| `opencli spotify next` | Skip to the next track |
+| `opencli spotify prev` | Skip to the previous track |
+| `opencli spotify volume <0-100>` | Set playback volume |
+| `opencli spotify search <query>` | Search Spotify tracks |
+| `opencli spotify queue <query>` | Add a track to the playback queue |
+| `opencli spotify shuffle <on|off>` | Toggle shuffle |
+| `opencli spotify repeat <off|track|context>` | Set repeat mode |
+
+## Usage Examples
+
+```bash
+# First-time setup
+opencli spotify auth
+
+# What is playing right now?
+opencli spotify status
+
+# Resume playback
+opencli spotify play
+
+# Search and immediately play a track
+opencli spotify play "Numb Linkin Park"
+
+# Search without playing
+opencli spotify search "Daft Punk" --limit 5 -f json
+
+# Queue a track
+opencli spotify queue "Get Lucky"
+
+# Playback controls
+opencli spotify pause
+opencli spotify next
+opencli spotify prev
+opencli spotify volume 35
+opencli spotify shuffle on
+opencli spotify repeat track
+```
+
+## Setup
+
+1. Create a Spotify app at <https://developer.spotify.com/dashboard>
+2. Add `http://127.0.0.1:8888/callback` to the app's Redirect URIs
+3. Fill in `SPOTIFY_CLIENT_ID` and `SPOTIFY_CLIENT_SECRET` in `~/.opencli/spotify.env`
+4. Run `opencli spotify auth`
+
+## Notes
+
+- Browser Bridge is not required.
+- Tokens are stored locally at `~/.opencli/spotify-tokens.json`.
+- Playback commands work best when you already have an active Spotify device/session.

docs/adapters/index.md

@@ -62,6 +62,7 @@ Run `opencli list` for the live registry.
 | **[barchart](/adapters/browser/barchart)** | `quote` `options` `greeks` `flow` | 🌐 Public |
 | **[hf](/adapters/browser/hf)** | `top` | 🌐 Public |
 | **[sinafinance](/adapters/browser/sinafinance)** | `news` | 🌐 Public |
+| **[spotify](/adapters/browser/spotify)** | `auth` `status` `play` `pause` `next` `prev` `volume` `search` `queue` `shuffle` `repeat` | 🔑 OAuth API |
 | **[stackoverflow](/adapters/browser/stackoverflow)** | `hot` `search` `bounties` `unanswered` | 🌐 Public |
 | **[wikipedia](/adapters/browser/wikipedia)** | `search` `summary` `random` `trending` | 🌐 Public |
 | **[lobsters](/adapters/browser/lobsters)** | `hot` `newest` `active` `tag` | 🌐 Public |

scripts/postinstall.js

@@ -196,6 +196,22 @@ function main() {
     }
   }
 
+  // ── Spotify credentials template ────────────────────────────────────
+  const opencliDir = join(home, '.opencli');
+  const spotifyEnvFile = join(opencliDir, 'spotify.env');
+  ensureDir(opencliDir);
+  if (!existsSync(spotifyEnvFile)) {
+    writeFileSync(spotifyEnvFile,
+      `# Spotify credentials — get them at https://developer.spotify.com/dashboard\n` +
+      `# Add http://127.0.0.1:8888/callback as a Redirect URI in your Spotify app\n` +
+      `SPOTIFY_CLIENT_ID=\n` +
+      `SPOTIFY_CLIENT_SECRET=\n`,
+      'utf8'
+    );
+    console.log(`✓ Spotify credentials template created at ${spotifyEnvFile}`);
+    console.log(`  Fill in your Client ID and Secret, then run: opencli spotify auth`);
+  }
+
   // ── Browser Bridge setup hint ───────────────────────────────────────
   console.log('');
   console.log('  \x1b[1mNext step — Browser Bridge setup\x1b[0m');