plx-converter 0.1.4 → 0.1.6

package/dist/browser.js

@@ -243,3 +243,18 @@ export function fetchBrowserCredentials() {
     }
     return credentials;
 }
+// Why auto-fetch came back empty, said in the terms of the platform the user is actually on. macOS
+// is the only place a denied Keychain prompt can be the answer; everywhere else Firefox is the only
+// backend, so the useful thing to report is which half of that is missing. This says *why* only —
+// the caller owns pointing at the manual paste, so that instruction lives in one place. Both inputs
+// are injected so the branches are testable without a browser or a second OS.
+export function autoFetchHint(os = platform(), firefoxFound = firefoxProfiles().length > 0) {
+    if (os === 'darwin')
+        return 'No browser was logged in, or the macOS Keychain prompt was denied.';
+    if (firefoxFound)
+        return 'A Firefox profile was found but held none of the cookies — log in at the provider in Firefox and retry.';
+    const why = os === 'win32'
+        ? 'Chrome/Edge cookies are sealed by App-Bound Encryption that only a SYSTEM process can unwrap'
+        : 'the Chromium keyring backends are not implemented here';
+    return `Auto-fetch supports Firefox only on this OS and no Firefox profile was found — ${why}.`;
+}

package/dist/cli.js

@@ -1,36 +1,67 @@
 #!/usr/bin/env node
 import { confirm, intro, isCancel, outro, password, select, text } from '@clack/prompts';
+import { autoFetchHint } from './browser.js';
 import { credential, loadConfig, saveCredential, saveRecentUrl, tryAutoFillCredentials } from './config.js';
 import { Conversion } from './conversion.js';
 import { PROVIDERS, inferSource, providerFor, targetKeys } from './registry.js';
 import { HELP_TEXT, parseArgs } from './args.js';
 function args() { return process.argv.slice(2); }
 // --- Credentials -----------------------------------------------------------
-// Fill one provider's credential: browser auto-fill first, then a manual paste. Persists what it
-// gets. Returns the credential, or null when the user cancels.
+// Why the browser read came back with nothing for this provider, and what to do instead. Every
+// auto-fetch failure says this, so the user never sees a bare "could not be fetched".
+function explainAutoFetchFailure(spec) {
+    const what = spec ? `${spec.label} cookies` : 'No credentials';
+    console.log(`✗ ${what} could not be read from your browser. ${autoFetchHint()}`);
+}
+// One manual paste, with where to find the value and what a correct one looks like.
+async function promptCredential(cfg, spec) {
+    console.log(`ℹ️ Where to find it: ${spec.credentialHint}`);
+    console.log(`   Looks like:      ${spec.credentialExample}`);
+    const entered = await password({ message: `Paste ${spec.credentialLabel}` });
+    if (isCancel(entered) || !entered)
+        return false;
+    await saveCredential(cfg, spec.key, String(entered).trim()); // pasted values carry stray whitespace
+    return true;
+}
+// Fill one provider's credential mid-conversion: browser auto-fill first, then a manual paste.
+// Persists what it gets. Returns the credential, or null when the user cancels.
 async function ensureCredential(cfg, spec) {
     if (credential(cfg, spec.key))
         return credential(cfg, spec.key);
     const filled = await tryAutoFillCredentials(cfg);
     if (filled.includes(spec.key))
         return credential(cfg, spec.key);
-    const entered = await password({ message: `${spec.credentialLabel} (${spec.credentialHint})` });
-    if (isCancel(entered) || !entered)
+    explainAutoFetchFailure(spec);
+    if (!(await promptCredential(cfg, spec)))
         return null;
-    await saveCredential(cfg, spec.key, String(entered));
     return credential(cfg, spec.key);
 }
-// Settings entry for one provider's credential: unlike ensureCredential this always asks, so a
-// saved-but-expired credential can be replaced. Proves it against the live service before saying so.
+// Settings entry for one provider's credential. The two ways in are offered as a choice rather than
+// auto-first-then-manual, so someone who knows the browser read will fail (or who wants to replace a
+// saved-but-expired value with a cookie of their own) can go straight to the paste. Auto-fetch here
+// overwrites, scoped to this provider, so an expired credential is actually replaced.
+// Proves whatever lands against the live service before saying it worked.
 async function reenterCredential(cfg, spec) {
-    warnLogin(spec.loginSite);
-    const filled = await tryAutoFillCredentials(cfg);
-    if (!filled.includes(spec.key)) {
-        const entered = await password({ message: `${spec.credentialLabel} (${spec.credentialHint})` });
-        if (isCancel(entered) || !entered)
+    const how = await select({
+        message: `${spec.credentialLabel}`,
+        options: [
+            { value: 'auto', label: 'Auto-fetch from browser' },
+            { value: 'manual', label: 'Paste cookies manually' },
+        ],
+    });
+    if (isCancel(how))
+        return;
+    if (how === 'auto') {
+        warnLogin(spec.loginSite);
+        if ((await tryAutoFillCredentials(cfg, true, spec.key)).includes(spec.key)) {
+            await report(cfg, spec);
             return;
-        await saveCredential(cfg, spec.key, String(entered));
+        }
+        explainAutoFetchFailure(spec);
+        console.log('   Paste it manually instead:');
     }
+    if (!(await promptCredential(cfg, spec)))
+        return;
     await report(cfg, spec);
 }
 // Check one provider's stored credential against the live service and say what happened.
@@ -241,16 +272,22 @@ async function runInteractive(options) {
         if (choice === 'autofetch') {
             warnLogin(PROVIDERS.map((p) => p.label).join(' & '));
             const filled = await tryAutoFillCredentials(cfg, true);
-            if (!filled.length) {
-                console.log('✗ No credentials could be fetched (browser not logged in / keychain denied).');
-                continue;
+            if (filled.length) {
+                console.log(`Fetched from browser: ${filled.join(', ')}. Checking…`);
+                for (const key of filled) {
+                    const spec = providerFor(key);
+                    if (spec)
+                        await report(cfg, spec);
+                }
             }
-            console.log(`Fetched from browser: ${filled.join(', ')}. Checking…`);
-            for (const key of filled) {
-                const spec = providerFor(key);
-                if (spec)
-                    await report(cfg, spec);
+            else {
+                explainAutoFetchFailure();
             }
+            // Whatever auto-fetch managed, the manual path is what closes the gap — name it and the menu
+            // entry that leads to it, rather than leaving the user at a dead end.
+            const missing = PROVIDERS.filter((p) => !credential(cfg, p.key));
+            if (missing.length)
+                console.log(`→ Still missing: ${missing.map((p) => p.label).join(', ')}. Add them from "Credentials: ${saved}/${PROVIDERS.length} saved" → pick the provider → "Paste cookies manually".`);
             continue;
         }
         if (choice === 'output') {

package/dist/config.js

@@ -63,14 +63,16 @@ async function write(patch) {
 // Semi-auto: fill credentials from a logged-in browser (pops the macOS Keychain "Allow" dialog on
 // first use), persist what's found, and return the provider names filled. By default only fills
 // providers with no credential yet (env vars and stored credentials win); pass overwrite=true to
-// refetch and replace. Never throws — a denied keychain / TCC block just fills nothing, and the
-// caller falls back to the manual paste prompt.
-export async function tryAutoFillCredentials(cfg, overwrite = false) {
-    if (!overwrite && Object.keys(ENV_VAR).every((provider) => cfg.credentials[provider]))
+// refetch and replace, and `only` to confine that to one provider — the Credentials menu refetches
+// the provider being edited without quietly replacing the other two. Never throws — a denied
+// keychain / TCC block just fills nothing, and the caller falls back to the manual paste prompt.
+export async function tryAutoFillCredentials(cfg, overwrite = false, only) {
+    const wanted = only ? [only] : Object.keys(ENV_VAR);
+    if (!overwrite && wanted.every((provider) => cfg.credentials[provider]))
         return [];
     const filled = [];
     for (const [provider, value] of Object.entries(fetchBrowserCredentials())) {
-        if (!value || (!overwrite && cfg.credentials[provider]))
+        if (!value || !wanted.includes(provider) || (!overwrite && cfg.credentials[provider]))
             continue;
         cfg.credentials[provider] = value;
         filled.push(provider);

package/dist/deezer.js

@@ -1,6 +1,6 @@
 import { z } from 'zod';
 import { fetchJson, retry } from './http.js';
-import { firstArtist, matchCandidates, searchQuery, stripFeat } from './matcher.js';
+import { firstArtist, matchByDuration, matchCandidates, searchQuery, stripFeat } from './matcher.js';
 const gqlSchema = z.object({ errors: z.array(z.object({ message: z.string() })).optional(), data: z.unknown() });
 const API = 'https://api.deezer.com';
 const GQL = 'https://pipe.deezer.com/api';
@@ -67,16 +67,22 @@ export class DeezerClient {
         const toCandidates = (data) => data.data.map((x) => ({ id: String(x.id), title: x.title, artist: x.artist.name, duration: x.duration }));
         const free = `${API}/search?${new URLSearchParams({ q: searchQuery(track.name, track.artist), limit: '5' })}`;
         const data = await retry(async () => fetchJson(free));
-        const match = matchCandidates(track.name, track.artist, track.durationMs, toCandidates(data));
+        const candidates = toCandidates(data);
+        const match = matchCandidates(track.name, track.artist, track.durationMs, candidates);
         if (match)
             return match;
         // Free-text relevance ranks covers/remixes above the real K-pop track; fall back to field syntax.
         const field = `${API}/search?${new URLSearchParams({ q: `track:"${stripFeat(track.name)}" artist:"${firstArtist(track.artist)}"`, limit: '5' })}`;
         const data2 = await retry(async () => fetchJson(field));
-        const match2 = matchCandidates(track.name, track.artist, track.durationMs, toCandidates(data2));
+        const candidates2 = toCandidates(data2);
+        const match2 = matchCandidates(track.name, track.artist, track.durationMs, candidates2);
         if (match2)
             return match2;
-        return this.searchByAlbum(track);
+        // The catalog scan still compares titles, so it stays ahead of the title-blind tier.
+        const byAlbum = await this.searchByAlbum(track);
+        if (byAlbum)
+            return byAlbum;
+        return matchByDuration(track.name, track.artist, track.durationMs, [...candidates, ...candidates2]);
     }
     // Artist → albums → album tracks, for tracks the search index never surfaces (e.g. "Salty & Sweet").
     async searchByAlbum(track) {

package/dist/matcher.js

@@ -22,6 +22,49 @@ export function matchCandidates(title, artist, durationMs, candidates) {
     }
     return null;
 }
+// A recording that is a *version* of the source rather than the source itself. Tested against the
+// raw title, not the normalized one: normalize() strips parenthesised text, which is exactly where
+// the marker lives ("estrangement(Instrumental)" and "estrangement" normalize to the same string).
+const VERSION_MARKER = /instrumental|karaoke|off ?vocal|acoustic|remix|live|cover|伴奏/i;
+function artistOverlaps(a, b) { return Boolean(a && b) && (a.includes(b) || b.includes(a)); }
+// Last-resort tier: the title is not compared at all. A catalog often carries a track under a
+// translated title — Deezer lists 红线 as "RED LINE", 愛你但說不出口 as "Hard to say" — so a search
+// built from the source title returns the right recording under a name that can never string-match.
+//
+// With the title gone, duration is the only real guard, so it tightens to 2s and a candidate
+// without one is rejected. Artist equality relaxes to containment (Spotify's "LBI利比" is Deezer's
+// "LBI"), and the guard that carries the weight is uniqueness: exactly one surviving candidate, or
+// no match. Version-marked candidates drop out first, unless the source is itself a version.
+//
+// Only ever call this on relevance-ranked search results. Run over a whole artist catalog it will
+// happily pair a source track with whatever unrelated release happens to share its length.
+export function matchByDuration(title, artist, durationMs, candidates) {
+    if (durationMs == null)
+        return null;
+    const na = artistKey(firstArtist(artist));
+    if (!na)
+        return null;
+    const sourceIsVersion = VERSION_MARKER.test(title);
+    const seen = new Set();
+    const hits = candidates.filter((c) => {
+        if (seen.has(c.id))
+            return false; // the same recording found by two queries is still one candidate
+        if (c.duration == null || !matchDurationMs(durationMs, c.duration, 2000))
+            return false;
+        if (!artistOverlaps(na, artistKey(c.artist)))
+            return false;
+        if (!sourceIsVersion && VERSION_MARKER.test(c.title))
+            return false;
+        seen.add(c.id);
+        return true;
+    });
+    // ponytail: two ids for the same recording (single + album release) read as ambiguous and are
+    // rejected. Collapse on normalized title if that turns out to cost real matches.
+    if (hits.length !== 1)
+        return null;
+    const [c] = hits;
+    return { id: c.id, title: c.title, artist: c.artist, method: 'duration-only' };
+}
 // Match rules for a music video, used only after the catalog has produced nothing.
 //
 // A music video's stated artist is usually the uploading channel, so the artist rule relaxes from

package/dist/registry.js

@@ -8,6 +8,7 @@ const spotify = {
     matches: ['open.spotify.com', 'spotify:playlist:'],
     credentialLabel: 'Spotify sp_dc',
     credentialHint: 'login open.spotify.com → F12 → Application → Cookies → sp_dc → copy value',
+    credentialExample: 'AQBv7pC3...9Kk  (the value only, ~150 chars, no "sp_dc=" prefix)',
     loginSite: 'Spotify (open.spotify.com)',
     anonymousRead: true,
     parseRef: async (ref) => parsePlaylistId(ref),
@@ -23,6 +24,7 @@ const deezer = {
     matches: ['deezer.com', 'link.deezer.com'],
     credentialLabel: 'Deezer ARL',
     credentialHint: 'login deezer.com → F12 → Application → Cookies → arl → copy value',
+    credentialExample: '3f9a1c...e7b2  (the value only, 192 hex chars, no "arl=" prefix)',
     loginSite: 'Deezer (deezer.com)',
     // Deezer's search is public, but reading a *playlist* goes through the authenticated GraphQL API.
     anonymousRead: false,
@@ -45,6 +47,7 @@ const ytmusic = {
     matches: ['music.youtube.com', 'youtube.com'],
     credentialLabel: 'YouTube Music cookies',
     credentialHint: 'login music.youtube.com → F12 → Network → any request → Request Headers → copy the whole "cookie:" value',
+    credentialExample: 'SAPISID=xxx; __Secure-3PAPISID=xxx; SID=xxx; __Secure-3PSID=xxx; __Secure-3PSIDTS=xxx; HSID=xxx; SSID=xxx; APISID=xxx  (one line, every cookie, SAPISID is required)',
     loginSite: 'YouTube Music (music.youtube.com)',
     anonymousRead: false,
     parseRef: async (ref) => parsePlaylistRef(ref),

package/dist/spotify.js

@@ -1,7 +1,7 @@
 import { createHmac } from 'node:crypto';
 import { z } from 'zod';
 import { browserHeaders, fetchJson, fetchText } from './http.js';
-import { matchCandidates, searchQuery } from './matcher.js';
+import { matchByDuration, matchCandidates, searchQuery } from './matcher.js';
 const PATHFINDER_URL = 'https://api-partner.spotify.com/pathfinder/v1/query';
 const FETCH_PLAYLIST_SHA = 'a65e12194ed5fc443a1cdebed5fabe33ca5b07b987185d63c72483867ad13cb4';
 export const EMBED_TRACK_LIMIT = 100;
@@ -221,7 +221,8 @@ export class SpotifyProvider {
     readPlaylist(ref) { return readPlaylist(parsePlaylistId(ref), this.token); }
     async search(track) {
         const candidates = await searchTrack(searchQuery(track.name, track.artist), this.token);
-        return matchCandidates(track.name, track.artist, track.durationMs, candidates);
+        return matchCandidates(track.name, track.artist, track.durationMs, candidates)
+            ?? matchByDuration(track.name, track.artist, track.durationMs, candidates);
     }
     createPlaylist(title) { return createPlaylist(title, this.token); }
     // Returns the count submitted, not one the service confirmed: addToPlaylist reports transport

package/dist/ytmusic-provider.js

@@ -1,4 +1,4 @@
-import { matchCandidates, matchVideoCandidates, searchQuery } from './matcher.js';
+import { matchByDuration, matchCandidates, matchVideoCandidates, searchQuery } from './matcher.js';
 import { innertube, isMix, parsePlaylistRef } from './ytmusic.js';
 import { continuationToken, parseItems, playlistTitle, toCandidate } from './ytmusic-parse.js';
 // Search filter params, as the web client sends them: catalog songs, and music videos.
@@ -57,9 +57,14 @@ export class YtMusicProvider {
     // strategy, the matcher owns the rules).
     async search(track) {
         const songs = await this.searchItems(track, SONGS);
-        const song = matchCandidates(track.name, track.artist, track.durationMs, songs.filter((i) => i.isSong).map(toCandidate));
+        const songCandidates = songs.filter((i) => i.isSong).map(toCandidate);
+        const song = matchCandidates(track.name, track.artist, track.durationMs, songCandidates);
         if (song)
             return song;
+        // A catalog song under a translated title still beats a video — see matchByDuration.
+        const translated = matchByDuration(track.name, track.artist, track.durationMs, songCandidates);
+        if (translated)
+            return translated;
         const videos = await this.searchItems(track, VIDEOS);
         return matchVideoCandidates(track.name, track.artist, track.durationMs, videos.map(toCandidate));
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "plx-converter",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "Convert playlists between Spotify, Deezer, and YouTube Music using your own browser session",
   "license": "MIT",
   "repository": {