feat(suno): add suno.com music-generation adapter

[ele-yufo]

Summary

A new browser-based adapter for Suno, the AI music generation service. Targets the /api/generate/v2-web/ schema introduced in 2026-05 and the cookie-isolation-aware Bearer auth path.

Commands

Command	Purpose
opencli suno status	login state, plan, credit breakdown, captcha
opencli suno list	list recent clips in the user's library
opencli suno generate	Simple or Custom mode generation + download
opencli suno download	fetch an existing clip by id in MP3 / M4A / WAV / cover

Each generate request returns 2 candidate clips (Suno's native A/B). All formats land alongside a metadata JSON dump for traceability.

Custom-mode controls (matches the web UI)

• --lyrics + --tags + --negative-tags + --title
• --weirdness (0..1) → metadata.control_sliders.weirdness_constraint
• --style-weight (0..1) → metadata.control_sliders.style_weight
• --instrumental, --model (chirp-fenix / chirp-bluejay / chirp-v4 / chirp-v3-5)

Paid-format guard

WAV downloads charge against the user's account (the Suno UI's Download → WAV flow makes the same billing/clips/{id}/download/ call). Both generate and download skip WAV by default and require --confirm-paid true to actually charge — surfaced in the result row as skipped(needs --confirm-paid):wav rather than silently dropping it.

Auth notes (worth a reviewer's attention)

The studio API rejects the OpenCLI bridge's credentials: 'include' cross-origin fetch (third-party cookie isolation in the eval context). The adapter explicitly pulls the live Clerk JWT via await window.Clerk.session.getToken() and sends it as Authorization: Bearer, alongside the browser-token (anti-replay base64-encoded timestamp) and device-id (from the suno_device_id cookie) headers that the studio API also requires. This matches the wire format observed in a real /api/generate/v2-web/ request capture.

Validation

• `npx tsc --noEmit` — clean
• `opencli validate suno` — PASS, 0 errors, 0 warnings, 4 commands
• `npx vitest run --project adapter clis/suno/` — 47 tests pass across 4 files
• `npm test` — 3811 passing across 380 files
• Live (Pro account, 10 credits/song): two-clip generation completes end-to-end; MP3 (796 KB, 64 kbps 48 kHz), M4A (603 KB opus), and WAV (6.7 MB PCM 16-bit 48 kHz) all download intact; cover JPEG + metadata JSON also written.

Known gaps (intentional / deferrable)

• Stems extraction (12-track separation) — schema known from the capture (`task: 'gen_stem'`, `stem_type_id: 91`, `stem_task: 'twelve'`, `continue_clip_id: `), but not yet wired. Happy to follow up in a separate PR if reviewers want it included; stems are paid and the design space (one-shot vs poll for 12 separate child clips) is worth its own review pass.
• Captcha solving — `/api/c/check` is checked pre-flight and the command fails fast with a clear instruction if Suno requires a challenge. Solving captchas headlessly is out of scope.

Files

```
clis/suno/
├── utils.js (498) — session, Bearer auth, generation, polling, download helpers
├── generate.js (208) — main generate command (Simple + Custom + sliders)
├── download.js (120) — standalone clip download by id
├── status.js (54) — health check
├── list.js (65) — library pagination
├── utils.test.js (148) — pure-function tests (parseFormats, sliders, sanitizers)
├── generate.test.js (206) — generate flow + argument validation + paid-format guard
├── download.test.js (98) — download by id + clip-id parsing + paid-format guard
└── commands.test.js (125) — status + list end-to-end (mocked utils)
```

Total: +1522 lines, 47 tests.