mcp-lyricscom 1.4.1 → 2.0.0

package/dist/lyricscom/client.js

@@ -1,5 +1,8 @@
+// src/config.ts
+import process from "process";
+
 // src/version.ts
-var PKG_VERSION = "1.4.1";
+var PKG_VERSION = "2.0.0";
 var REPO_URL = "https://github.com/smeet666/mcp-lyricscom";
 
 // src/config.ts
@@ -16,7 +19,9 @@ var MIN_ALLOWED_INTERVAL_MS = 500;
 var LOG_LEVELS = ["silent", "error", "info", "debug"];
 function readNumber(name, env, range) {
   const raw = env[name];
-  if (raw === void 0 || raw.trim() === "") return range.fallback;
+  if (raw === void 0 || raw.trim() === "") {
+    return range.fallback;
+  }
   const parsed = Number(raw);
   if (!Number.isFinite(parsed)) {
     warn(`${name}="${raw}" is not a number, using ${range.fallback}`);
@@ -34,7 +39,9 @@ function warn(message) {
 }
 function readInterval(env) {
   const raw = env.LYRICSCOM_MIN_INTERVAL_MS;
-  if (raw === void 0 || raw.trim() === "") return DEFAULTS.minIntervalMs;
+  if (raw === void 0 || raw.trim() === "") {
+    return DEFAULTS.minIntervalMs;
+  }
   const parsed = Number(raw);
   if (!Number.isFinite(parsed)) {
     warn(`LYRICSCOM_MIN_INTERVAL_MS="${raw}" is not a number, using ${DEFAULTS.minIntervalMs}ms`);
@@ -112,7 +119,9 @@ var TtlLruCache = class {
   store = /* @__PURE__ */ new Map();
   get(key) {
     const entry = this.store.get(key);
-    if (!entry) return void 0;
+    if (!entry) {
+      return void 0;
+    }
     if (Date.now() >= entry.expiresAt) {
       this.store.delete(key);
       return void 0;
@@ -122,12 +131,16 @@ var TtlLruCache = class {
     return entry.value;
   }
   set(key, value) {
-    if (this.maxEntries <= 0 || this.ttlMs <= 0) return;
+    if (this.maxEntries <= 0 || this.ttlMs <= 0) {
+      return;
+    }
     this.store.delete(key);
     this.store.set(key, { value, expiresAt: Date.now() + this.ttlMs });
     while (this.store.size > this.maxEntries) {
       const oldest = this.store.keys().next();
-      if (oldest.done) break;
+      if (oldest.done) {
+        break;
+      }
       this.store.delete(oldest.value);
     }
   }
@@ -192,17 +205,32 @@ function invalidInput(message, hint) {
 }
 
 // src/lyricscom/parsers/detectThrottle.ts
+var CLOSING_HTML_TAG = /<\/html>/i;
 var MIN_PLAUSIBLE_HTML = 2e3;
 function classifyResponse(status, body) {
-  if (status === 202) return { kind: "throttled", reason: "status-202" };
-  if (status === 429) return { kind: "throttled", reason: "status-429" };
-  if (status === 503) return { kind: "throttled", reason: "status-503" };
-  if (status === 403) return { kind: "blocked", status };
-  if (status === 404) return { kind: "not-found" };
-  if (status >= 500) return { kind: "server-error", status };
+  if (status === 202) {
+    return { kind: "throttled", reason: "status-202" };
+  }
+  if (status === 429) {
+    return { kind: "throttled", reason: "status-429" };
+  }
+  if (status === 503) {
+    return { kind: "throttled", reason: "status-503" };
+  }
+  if (status === 403) {
+    return { kind: "blocked", status };
+  }
+  if (status === 404) {
+    return { kind: "not-found" };
+  }
+  if (status >= 500) {
+    return { kind: "server-error", status };
+  }
   const trimmed = body.trim();
-  if (trimmed.length === 0) return { kind: "throttled", reason: "empty-body" };
-  if (trimmed.length < MIN_PLAUSIBLE_HTML && !/<\/html>/i.test(trimmed)) {
+  if (trimmed.length === 0) {
+    return { kind: "throttled", reason: "empty-body" };
+  }
+  if (trimmed.length < MIN_PLAUSIBLE_HTML && !CLOSING_HTML_TAG.test(trimmed)) {
     return { kind: "throttled", reason: "short-body" };
   }
   return { kind: "ok", html: body };
@@ -258,10 +286,14 @@ var RateLimiter = class {
     this.intervalMs = Math.max(this.baseIntervalMs, Math.floor(this.intervalMs * 0.75));
   }
   async waitForSlot() {
-    if (this.intervalMs === 0 || this.lastStart === 0) return;
+    if (this.intervalMs === 0 || this.lastStart === 0) {
+      return;
+    }
     const elapsed = Date.now() - this.lastStart;
     const remaining = Math.min(this.intervalMs, this.intervalMs - elapsed);
-    if (remaining > 0) await sleep(remaining);
+    if (remaining > 0) {
+      await sleep(remaining);
+    }
   }
 };
 function sleep(ms) {
@@ -280,7 +312,7 @@ function backoffDelay(attempt, random = Math.random) {
 async function fetchHtml(url, deps) {
   const { config, limiter, logger } = deps;
   const doFetch = deps.fetchImpl ?? fetch;
-  return limiter.schedule(async () => {
+  return await limiter.schedule(async () => {
     let lastError;
     let askedWaitMs = null;
     for (let attempt = 0; attempt <= config.maxRetries; attempt += 1) {
@@ -340,21 +372,38 @@ async function fetchHtml(url, deps) {
           throw blockedUserAgent(url);
         case "not-found":
           throw notFound(url);
+        // Every kind the classifier declares is handled above, and the linter
+        // holds that. This clause is the runtime backstop: a response nothing
+        // above matched leaves as an error rather than as a silent retry.
+        default:
+          throw new LyricsComError(
+            "network_error",
+            `lyrics.com returned a response this client cannot classify for ${url}.`,
+            { url }
+          );
       }
     }
     throw lastError ?? new LyricsComError("network_error", `Could not fetch ${url}.`, { url });
   });
 }
 function parseRetryAfter(raw) {
-  if (!raw) return null;
+  if (!raw) {
+    return null;
+  }
   const seconds = Number(raw.trim());
-  if (Number.isFinite(seconds) && seconds >= 0) return Math.round(seconds * 1e3);
+  if (Number.isFinite(seconds) && seconds >= 0) {
+    return Math.round(seconds * 1e3);
+  }
   const when = Date.parse(raw);
-  if (Number.isNaN(when)) return null;
+  if (Number.isNaN(when)) {
+    return null;
+  }
   return Math.max(0, when - Date.now());
 }
 function asTransportError(error, url) {
-  if (error instanceof LyricsComError) return error;
+  if (error instanceof LyricsComError) {
+    return error;
+  }
   const name = error instanceof Error ? error.name : "";
   if (name === "TimeoutError" || name === "AbortError") {
     return new LyricsComError("timeout", "lyrics.com did not answer in time.", {
@@ -367,9 +416,11 @@ function asTransportError(error, url) {
 }
 
 // src/lyricscom/parsers/searchResults.ts
-import * as cheerio from "cheerio";
+import process2 from "process";
+import { load } from "cheerio";
 
 // src/text/normalize.ts
+var MOJIBAKE_MARKS = /[ÃÂ]/;
 var HTML_ENTITIES = {
   amp: "&",
   lt: "<",
@@ -386,12 +437,16 @@ var HTML_ENTITIES = {
   rdquo: "\u201D"
 };
 function unescapeHtml(text) {
-  if (!text) return text;
+  if (!text) {
+    return text;
+  }
   return text.replace(/&(#x?[0-9a-fA-F]+|[a-zA-Z][a-zA-Z0-9]*);/g, (match, entity) => {
     if (entity.startsWith("#")) {
       const isHex = entity[1] === "x" || entity[1] === "X";
       const codePoint = Number.parseInt(isHex ? entity.slice(2) : entity.slice(1), isHex ? 16 : 10);
-      if (Number.isNaN(codePoint) || codePoint < 0 || codePoint > 1114111) return match;
+      if (Number.isNaN(codePoint) || codePoint < 0 || codePoint > 1114111) {
+        return match;
+      }
       try {
         return String.fromCodePoint(codePoint);
       } catch {
@@ -402,10 +457,14 @@ function unescapeHtml(text) {
   });
 }
 function fixEncodingIssues(text) {
-  if (!text || !/[ÃÂ]/.test(text)) return text;
+  if (!(text && MOJIBAKE_MARKS.test(text))) {
+    return text;
+  }
   try {
     const repaired = Buffer.from(text, "latin1").toString("utf8");
-    if (repaired.includes("\uFFFD")) return text;
+    if (repaired.includes("\uFFFD")) {
+      return text;
+    }
     return repaired;
   } catch {
     return text;
@@ -415,23 +474,33 @@ function collapseWhitespace(text) {
   return text.replace(/\s+/g, " ").trim();
 }
 function cleanInlineText(text) {
-  if (!text) return "";
+  if (!text) {
+    return "";
+  }
   return collapseWhitespace(fixEncodingIssues(unescapeHtml(text)));
 }
 function cleanLyricsText(text) {
-  if (!text) return "";
+  if (!text) {
+    return "";
+  }
   const normalized = fixEncodingIssues(unescapeHtml(text)).replace(/\r\n?/g, "\n");
   const lines = normalized.split("\n").map((line) => line.trim());
   const out = [];
   for (const line of lines) {
-    if (line === "" && (out.length === 0 || out[out.length - 1] === "")) continue;
+    if (line === "" && (out.length === 0 || out.at(-1) === "")) {
+      continue;
+    }
     out.push(line);
   }
-  while (out.length > 0 && out[out.length - 1] === "") out.pop();
+  while (out.length > 0 && out.at(-1) === "") {
+    out.pop();
+  }
   return out.join("\n");
 }
 
 // src/lyricscom/urls.ts
+var ABSOLUTE_URL = /^https?:\/\//i;
+var DIGITS_ONLY = /^\d+$/;
 var BASE_URL = "https://www.lyrics.com";
 var RESULTS_PER_PAGE = 24;
 var SONG_HREF_RE = /^\/lyric(?:-lf)?\/(\d+)\//;
@@ -441,7 +510,9 @@ function encodeTerm(term) {
 }
 function buildSearchUrl(term, page) {
   const encoded = encodeTerm(term);
-  if (page <= 1) return `${BASE_URL}/lyrics/${encoded}`;
+  if (page <= 1) {
+    return `${BASE_URL}/lyrics/${encoded}`;
+  }
   return `${BASE_URL}/serp.php?st=${encoded}&p=${page}`;
 }
 function buildSongUrl(id) {
@@ -454,22 +525,28 @@ function isLyricsComHost(rawUrl) {
   } catch {
     return false;
   }
-  if (parsed.protocol !== "https:" && parsed.protocol !== "http:") return false;
+  if (parsed.protocol !== "https:" && parsed.protocol !== "http:") {
+    return false;
+  }
   return ALLOWED_HOSTS.has(parsed.hostname.toLowerCase());
 }
 function extractSongId(hrefOrUrl) {
   let path = hrefOrUrl;
-  if (/^https?:\/\//i.test(hrefOrUrl)) {
-    if (!isLyricsComHost(hrefOrUrl)) return null;
+  if (ABSOLUTE_URL.test(hrefOrUrl)) {
+    if (!isLyricsComHost(hrefOrUrl)) {
+      return null;
+    }
     path = new URL(hrefOrUrl).pathname;
   }
-  if (!path.startsWith("/")) path = `/${path}`;
+  if (!path.startsWith("/")) {
+    path = `/${path}`;
+  }
   const match = SONG_HREF_RE.exec(path);
   return match?.[1] ?? null;
 }
 function resolveSongRef(input) {
   if (input.id) {
-    if (!/^\d+$/.test(input.id)) {
+    if (!DIGITS_ONLY.test(input.id)) {
       throw invalidInput(
         `"${input.id}" is not a lyrics.com song id.`,
         "Ids are digits only, as returned by the search tools."
@@ -527,8 +604,9 @@ var SEL = {
 };
 
 // src/lyricscom/parsers/searchResults.ts
+var YEAR = /\b(1[89]\d{2}|20\d{2})\b/;
 function parseSearchResults(html, options) {
-  const $ = cheerio.load(html);
+  const $ = load(html);
   const rows = $(SEL.serpItem);
   if (rows.length === 0) {
     if ($(SEL.serpShell).length === 0) {
@@ -545,7 +623,7 @@ function parseSearchResults(html, options) {
     const title = cleanInlineText(titleLink.text());
     const artist = cleanInlineText(row.find(SEL.resultArtist).first().text());
     const id = href ? extractSongId(href) : null;
-    if (!id || !title || !artist) {
+    if (!(id && title && artist)) {
       skipped += 1;
       return;
     }
@@ -567,7 +645,7 @@ function parseSearchResults(html, options) {
     throw parseFailure(options.url, `${rows.length} result rows matched but none could be read`);
   }
   if (skipped > 0) {
-    process.stderr.write(
+    process2.stderr.write(
       `[mcp-lyricscom] skipped ${skipped} unreadable result rows on ${options.url}
 `
     );
@@ -580,20 +658,23 @@ function parseSearchResults(html, options) {
   };
 }
 function parseYear(raw) {
-  const match = /\b(1[89]\d{2}|20\d{2})\b/.exec(raw);
-  if (!match?.[1]) return null;
+  const match = YEAR.exec(raw);
+  if (!match?.[1]) {
+    return null;
+  }
   return Number.parseInt(match[1], 10);
 }
 
 // src/lyricscom/parsers/songPage.ts
-import * as cheerio2 from "cheerio";
+import { load as load2 } from "cheerio";
+var NO_LYRICS_FOUND = /no lyrics found/i;
 function parseSongPage(html, options) {
-  const $ = cheerio2.load(html);
+  const $ = load2(html);
   const title = cleanInlineText($(SEL.songTitle).first().text()) || null;
   const artist = cleanInlineText($(SEL.songArtist).first().text()) || null;
   const body = $(SEL.songBody).first();
   if (body.length === 0) {
-    const declaresNoLyrics = $(SEL.songNoData).length > 0 || /no lyrics found/i.test($("title").text());
+    const declaresNoLyrics = $(SEL.songNoData).length > 0 || NO_LYRICS_FOUND.test($("title").text());
     if (!declaresNoLyrics) {
       throw parseFailure(options.url, "no lyrics container and no 'no lyrics' marker");
     }
@@ -609,12 +690,13 @@ function extractBodyText($, body) {
   const rawHtml = $.html(body);
   const withoutAnchors = rawHtml.replace(/<a[^>]*>([\s\S]*?)<\/a>/gi, "$1");
   const withNewlines = withoutAnchors.replace(/<br\s*\/?>/gi, "\n");
-  return cheerio2.load(withNewlines).root().text();
+  return load2(withNewlines).root().text();
 }
 
 // src/lyricscom/client.ts
+var BROWSER_IDENTITY = /mozilla\/|applewebkit|chrome\/|safari\/|gecko/i;
 function withGuarantees(config) {
-  const userAgent = /mozilla\/|applewebkit|chrome\/|safari\/|gecko/i.test(config.userAgent) ? `${config.userAgent} ${DEFAULT_USER_AGENT}` : config.userAgent;
+  const userAgent = BROWSER_IDENTITY.test(config.userAgent) ? `${config.userAgent} ${DEFAULT_USER_AGENT}` : config.userAgent;
   return {
     ...config,
     userAgent,
@@ -636,11 +718,11 @@ var LyricsComClient = class {
   }
   async search(term, page) {
     const url = buildSearchUrl(term, page);
-    return this.fetchParsed(url, (html) => parseSearchResults(html, { page, url }));
+    return await this.fetchParsed(url, (html) => parseSearchResults(html, { page, url }));
   }
   async getSong(ref) {
     const { id, url } = resolveSongRef(ref);
-    return this.fetchParsed(url, (html) => parseSongPage(html, { id, url }));
+    return await this.fetchParsed(url, (html) => parseSongPage(html, { id, url }));
   }
   /**
    * Fetch, parse, then cache. In that order: a page that could not be read is