plx-converter 0.1.2 → 0.1.4

package/README.md

@@ -6,6 +6,8 @@ Converts a playlist from any of the three services into any other — six direct
 
 > ⚠️ **Personal, non-commercial use.** Uses unofficial web endpoints that can change or break without notice. Not affiliated with Spotify, Deezer, or YouTube.
 
+<img src="https://raw.githubusercontent.com/samlehoy/plx/master/screenshots/cli-interactive-menu.png" width="640" alt="plx interactive menu: Convert a playlist, Credentials 3/3 saved, Auto-fetch credentials from browser, Report, Quit" />
+
 ## Install
 
 ```bash
@@ -16,12 +18,18 @@ Requires Node.js ≥ 22.
 
 ## Usage
 
+Run `plx` with no arguments for the interactive menu, which walks you through source, target, and credentials:
+
+<img src="https://raw.githubusercontent.com/samlehoy/plx/master/screenshots/cli-provider-selection.png" width="640" alt="Interactive prompt picking a source provider between Spotify, Deezer, and YouTube Music" />
+
+Or name everything up front:
+
 ```bash
-plx                                                        # interactive menu
-plx --url "https://open.spotify.com/playlist/ID" --to deezer
-plx --url "https://www.deezer.com/playlist/ID" --to spotify
-plx --url "https://music.youtube.com/playlist?list=ID" --to deezer
-plx --url "<LINK>" --to deezer --dry-run                   # preview matches without writing
+plx                                                          # interactive menu
+plx --url "https://open.spotify.com/playlist/ID"   --to deezer
+plx --url "https://www.deezer.com/playlist/ID"     --to ytmusic
+plx --url "https://music.youtube.com/playlist?list=ID" --to spotify
+plx --url "<LINK>" --to deezer --dry-run                     # preview matches without writing
 ```
 
 You name the **target**; the source is inferred from the link, since the link already says which
@@ -30,20 +38,61 @@ service it belongs to. plx never guesses a destination — omitting `--to` is an
 ```text
 Options:
   -u, --url <LINK>        playlist URL/URI/ID (repeatable)
-  -t, --to <PROVIDER>     target provider (required)
+  -t, --to <PROVIDER>     target provider: spotify | deezer | ytmusic (required)
   -o, --output <file>     CSV report path (default: conversion_report.csv)
   -d, --dry-run           match only, don't write
   -h, --help              show help
 ```
 
+Every run writes a CSV report — one row per track, with the match method and target id, so you can
+see exactly what moved and what didn't.
+
 ## Credentials
 
-| Cookie | Env var | Needed for |
-|---|---|---|
-| Deezer `arl` | `DEEZER_ARL` | writing to Deezer |
-| Spotify `sp_dc` | `SPOTIFY_DC` | writing to a Spotify target |
+One browser session credential per provider. All are optional — you only need the ones your chosen
+direction actually touches.
+
+| Provider | Credential | Env var | Needed for |
+|---|---|---|---|
+| Spotify | `sp_dc` cookie | `SPOTIFY_DC` | writing to Spotify, or reading your *private* playlists |
+| Deezer | `arl` cookie | `DEEZER_ARL` | reading **or** writing a Deezer playlist |
+| YouTube Music | whole `cookie:` header | `YTMUSIC_COOKIE` | reading **or** writing a YouTube Music playlist |
+
+Reading a **public Spotify** playlist needs no credentials at all — which is what makes a
+credential-free `--dry-run` possible.
+
+**YouTube Music takes a whole cookie header, not a single cookie.** Google splits a session across a
+dozen-odd cookies, so copy the entire `cookie:` value: on [music.youtube.com](https://music.youtube.com),
+DevTools → **Network** → any request → **Request Headers** → `cookie:`. Google sessions also expire
+faster than the other two, so expect to redo this occasionally.
+
+### Auto-fetch from your browser
+
+Rather than copying cookies by hand, plx can read them straight from a logged-in browser. Pick
+**"Auto-fetch credentials (from browser)"** from the menu, or let it run automatically when a
+credential is missing. Manual paste stays the fallback everywhere.
+
+| Browser | macOS | Windows | Linux |
+|---|---|---|---|
+| Firefox | ✅ | ✅ | ✅ |
+| Chromium family (Brave, Chrome, Edge, Chromium, Vivaldi, Opera) | ✅ | — | — |
+| Safari | ✅ — needs Full Disk Access | — | — |
+
+On macOS the Chromium and Safari backends ask you to accept the Keychain prompt once. Firefox needs
+no prompt on any OS, since it stores cookie values unencrypted.
+
+Chromium on Windows isn't a gap waiting to be filled: since Chrome 127 the cookie key is sealed
+behind App-Bound Encryption that only a SYSTEM-level process can unwrap, and every published
+workaround is the sort of thing malware does. On Windows, use Firefox or paste manually.
+
+Set credentials in `.env`, export them in your shell, or paste when prompted. Full setup:
+[`docs/CONFIG.md`](docs/CONFIG.md).
+
+## Website
+
+[plx.sh](https://plx.sh) — overview, matching rules, and install steps.
 
-Set in `.env`, or paste when prompted. Reading a Spotify playlist needs **no credentials**. Full setup: [`docs/CONFIG.md`](docs/CONFIG.md).
+<img src="https://raw.githubusercontent.com/samlehoy/plx/master/screenshots/website-landing.png" width="640" alt="plx landing page: Move your playlist. No dev account." />
 
 ## Development
 

package/dist/browser.js

@@ -1,7 +1,7 @@
 import { createDecipheriv, pbkdf2Sync } from 'node:crypto';
 import { execFileSync } from 'node:child_process';
-import { existsSync, readFileSync } from 'node:fs';
-import { homedir, platform } from 'node:os';
+import { copyFileSync, existsSync, mkdtempSync, readFileSync, readdirSync, rmSync, statSync } from 'node:fs';
+import { homedir, platform, tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { DatabaseSync } from 'node:sqlite';
 import { YTMUSIC_COOKIES, cookieHeader } from './ytmusic.js';
@@ -156,17 +156,77 @@ function readSafari() {
     }
     return {};
 }
+// Firefox — the one backend that is not macOS-only. `cookies.sqlite` stores values in **plaintext**:
+// no keychain, no DPAPI, and none of the App-Bound Encryption that closed the Chromium family off on
+// Windows (Chrome 127+ wraps the cookie key in SYSTEM-DPAPI, so only a SYSTEM process can unwrap it,
+// and every published bypass is malware behaviour). `key4.db` is commonly assumed to encrypt these
+// too — it does not; it protects saved *logins*.
+const FIREFOX_ROOTS = {
+    win32: join(process.env.APPDATA ?? join(homedir(), 'AppData', 'Roaming'), 'Mozilla', 'Firefox'),
+    darwin: join(homedir(), 'Library', 'Application Support', 'Firefox'),
+    linux: join(homedir(), '.mozilla', 'firefox'),
+};
+// Every profile holding a cookie DB, most-recently-written first. `profiles.ini` names the default
+// one, but reading it needs an INI parser to answer worse than an mtime sort already does: someone
+// with several profiles is logged in on the one they actually use, which is the one just written to.
+export function firefoxProfiles(root = FIREFOX_ROOTS[platform()] ?? FIREFOX_ROOTS.linux) {
+    const nested = join(root, 'Profiles');
+    const base = existsSync(nested) ? nested : root; // some Linux packagings drop the Profiles/ level
+    try {
+        return readdirSync(base, { withFileTypes: true })
+            .filter((entry) => entry.isDirectory())
+            .map((entry) => join(base, entry.name, 'cookies.sqlite'))
+            .filter(existsSync)
+            .sort((a, b) => statSync(b).mtimeMs - statSync(a).mtimeMs);
+    }
+    catch {
+        return []; // no Firefox installed, or an unreadable profile root
+    }
+}
+// Firefox keeps the DB in WAL mode and holds it open while running — on Windows that lock is
+// enforced, so reading the file in place fails outright. Copy it to a temp dir and read the copy.
+// The `-wal` sidecar comes along because a cookie set this session may not be checkpointed into the
+// main file yet, and the copy is opened writable precisely so SQLite is allowed to replay it.
+export function readFirefox(dbPath) {
+    let dir = null;
+    try {
+        dir = mkdtempSync(join(tmpdir(), 'plx-ff-'));
+        const copy = join(dir, 'cookies.sqlite');
+        copyFileSync(dbPath, copy);
+        if (existsSync(`${dbPath}-wal`))
+            copyFileSync(`${dbPath}-wal`, `${copy}-wal`);
+        const db = new DatabaseSync(copy);
+        try {
+            const query = `SELECT name, host, value FROM moz_cookies WHERE name IN (${COOKIE_NAMES.map(() => '?').join(',')})`;
+            // `host` is stored dot-prefixed for domain cookies (`.youtube.com`); hostRank's endsWith arm
+            // already accepts that, so it is passed through as-is.
+            return collect(db.prepare(query).all(...COOKIE_NAMES));
+        }
+        finally {
+            db.close();
+        }
+    }
+    catch {
+        return {}; // unreadable profile / changed schema — skip it
+    }
+    finally {
+        if (dir)
+            rmSync(dir, { recursive: true, force: true });
+    }
+}
 // Auto-retrieve credentials from the first logged-in browser that has them, keyed by provider —
 // the parsers above speak in cookie names, and this is where that becomes one opaque string per
 // provider for the config layer to store. Never throws: a missing browser, locked DB, denied
 // keychain, or TCC block just yields {}. Manual paste stays the fallback.
 export function fetchBrowserCredentials() {
-    if (platform() !== 'darwin')
-        return {};
+    // The keychain-backed backends stay gated on macOS; Firefox runs everywhere and is all that
+    // Windows and Linux get. macOS keeps its original order, so nothing changes for anyone who
+    // already relied on this — Firefox only fills what the others left empty.
+    const keychainBacked = platform() === 'darwin' ? [...CHROMIUM_BROWSERS.map(readChromium), readSafari()] : [];
     const credentials = {};
     // Every backend is read rather than stopping at the first: a user may be logged into Deezer in one
     // browser and YouTube Music in another.
-    for (const found of [...CHROMIUM_BROWSERS.map(readChromium), readSafari()]) {
+    for (const found of [...keychainBacked, ...firefoxProfiles().map(readFirefox)]) {
         if (!credentials.deezer && found.arl)
             credentials.deezer = found.arl;
         if (!credentials.spotify && found.sp_dc)

package/dist/config.js

@@ -10,10 +10,15 @@ const ENV_VAR = { deezer: 'DEEZER_ARL', spotify: 'SPOTIFY_DC', ytmusic: 'YTMUSIC
 // migrated (see #1): they are ignored, dropped on the next write, and the user re-fetches or
 // re-pastes — which costs one browser dialog.
 const LEGACY_KEYS = ['deezerArl', 'spotifyDc'];
+// XDG_CONFIG_HOME wins on every platform, Windows included: it is the explicit override, and a
+// Windows-only branch that ignored it left the tests sharing one real %APPDATA% dir instead of a
+// temp dir each, so state leaked between them.
 export function configDir() {
+    if (process.env.XDG_CONFIG_HOME)
+        return join(process.env.XDG_CONFIG_HOME, 'plx');
     if (platform() === 'win32')
         return join(process.env.APPDATA ?? join(homedir(), 'AppData', 'Roaming'), 'plx');
-    return join(process.env.XDG_CONFIG_HOME ?? join(homedir(), '.config'), 'plx');
+    return join(homedir(), '.config', 'plx');
 }
 const file = () => join(configDir(), 'credentials.json');
 async function loadStored() { try {

package/package.json

@@ -1,8 +1,13 @@
 {
   "name": "plx-converter",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Convert playlists between Spotify, Deezer, and YouTube Music using your own browser session",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/samlehoy/plx.git"
+  },
+  "homepage": "https://plx.sh",
   "type": "module",
   "bin": {
     "plx": "dist/cli.js"
@@ -18,6 +23,7 @@
   "scripts": {
     "dev": "tsx src/cli.ts",
     "build": "tsc",
+    "prepublishOnly": "npm run build",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "lint": "eslint .",
@@ -26,7 +32,6 @@
   "dependencies": {
     "@clack/prompts": "^0.10.1",
     "dotenv": "^16.4.7",
-    "plx-converter": "^0.1.1",
     "zod": "^3.24.2"
   },
   "devDependencies": {