feat: make Jellyfin an optional source instead of the default

Revert the jellyfin-only default introduced by PR #123 so upgrading
users keep their online sources; Jellyfin becomes opt-in:

- default enabledProviders is now the online set (netease/qq/bilibili/
  youtube/kugou); defaultPlatform() uses a fixed priority order
  (netease -> qq -> kugou -> jellyfin -> bilibili -> youtube) instead
  of jellyfin-first, so chat/REST/WebUI default to netease again
- Settings: Jellyfin card is always visible with a new enable toggle
  (its enabled bit is enabledProviders membership); guards against
  clobbering other providers before the list loads
- Setup wizard: saving the Jellyfin step auto-enables the source when
  a server URL was entered
- Search/player store fallbacks flip from jellyfin to netease; !help
  no longer hardcodes Jellyfin lines
- tests: update default-platform assertions, add coverage for the new
  default set, legacy configs without enabledProviders, priority
  order, and explicit jellyfin-only configs
- README: reframe Jellyfin as optional (badges, command table, quality
  tiers, dedicated section, changelog), document the enabledProviders
  default and the v1.10.0 jellyfin-only window fix, credit @ItsEricRao

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

src/bot/instance.ts

@@ -731,8 +731,8 @@ export class BotInstance extends EventEmitter {
   }
 
   /** Chat-command source flags. No flag → the configured default platform
-   *  (jellyfin unless disabled). Netease is no longer the implicit default,
-   *  so it gets an explicit -n flag. */
+   *  (netease in the default config; otherwise the first enabled source by
+   *  fixed priority — see defaultPlatform()). */
   private static readonly FLAG_PLATFORMS: ReadonlyArray<[string, Platform]> = [
     ["b", "bilibili"],
     ["q", "qq"],
@@ -1451,7 +1451,6 @@ export class BotInstance extends EventEmitter {
     return [
       "TSMusicBot Commands:",
       `${p}play <song>  — Search and play (default source: ${def})`,
-      `${p}play -j <song> — Search from Jellyfin`,
       ...(flagHelp ? [`  Source flags: ${flagHelp}`] : []),
       `${p}search <name> — List top matches to pick a specific (same-name) song`,
       `${p}play #N       — Play the Nth result of the last ${p}search`,
@@ -1467,7 +1466,7 @@ export class BotInstance extends EventEmitter {
       `${p}mode <seq|loop|random|rloop> — Play mode`,
       `${p}playlist <name or id> — Load playlist by name or ID`,
       `${p}album <name or id> — Load album`,
-      `${p}fm           — Personal FM (Jellyfin: 收藏电台 Instant Mix)`,
+      `${p}fm           — Personal FM (default source: ${def}; source flags work too)`,
       `${p}artist <name> — Play songs by artist (loop)`,
       `${p}vote         — Vote to skip`,
       `${p}lyrics       — Show lyrics`,

src/data/config.test.ts

@@ -10,7 +10,7 @@ import {
   renameSync,
 } from "node:fs";
 import { tmpdir } from "node:os";
-import { getDefaultConfig, loadConfig, saveConfig, migrateLegacyConfig } from "./config.js";
+import { getDefaultConfig, loadConfig, saveConfig, migrateLegacyConfig, defaultPlatform } from "./config.js";
 
 // Wrap the fs functions config.ts uses in call-through spies so the atomic-write
 // and transient-read-error paths can be observed/forced. Everything else (mkdtemp,
@@ -48,6 +48,50 @@ describe("config", () => {
     expect(config).toEqual(getDefaultConfig());
   });
 
+  it("defaults to the online sources with jellyfin as opt-in (disabled)", () => {
+    const config = getDefaultConfig();
+    expect(config.enabledProviders).toEqual(["netease", "qq", "bilibili", "youtube", "kugou"]);
+    expect(config.enabledProviders).not.toContain("jellyfin");
+  });
+
+  it("keeps pre-gating behavior for legacy configs without enabledProviders", () => {
+    const dir = makeTmpDir();
+    const path = join(dir, "config.json");
+    // A config written before enabledProviders existed: no such field.
+    writeFileSync(path, JSON.stringify({ webPort: 4000 }));
+    const config = loadConfig(path);
+    expect(config.enabledProviders).toEqual(["netease", "qq", "bilibili", "youtube", "kugou"]);
+    expect(defaultPlatform(config)).toBe("netease");
+  });
+
+  it("defaultPlatform follows the fixed priority order", () => {
+    const config = getDefaultConfig();
+    expect(defaultPlatform(config)).toBe("netease");
+
+    // Jellyfin ranks after the online music platforms…
+    config.enabledProviders = ["netease", "jellyfin"];
+    expect(defaultPlatform(config)).toBe("netease");
+    // …but ahead of the video sites…
+    config.enabledProviders = ["bilibili", "jellyfin", "youtube"];
+    expect(defaultPlatform(config)).toBe("jellyfin");
+    // …and is the default when it is the only enabled source.
+    config.enabledProviders = ["jellyfin"];
+    expect(defaultPlatform(config)).toBe("jellyfin");
+    // Nothing enabled → netease fallback (the gate then reports it disabled).
+    config.enabledProviders = [];
+    expect(defaultPlatform(config)).toBe("netease");
+  });
+
+  it("respects an explicit jellyfin-only enabledProviders from disk", () => {
+    const dir = makeTmpDir();
+    const path = join(dir, "config.json");
+    // e.g. a config persisted by the short-lived jellyfin-by-default builds.
+    writeFileSync(path, JSON.stringify({ enabledProviders: ["jellyfin"] }));
+    const config = loadConfig(path);
+    expect(config.enabledProviders).toEqual(["jellyfin"]);
+    expect(defaultPlatform(config)).toBe("jellyfin");
+  });
+
   it("creates config file on save", () => {
     const dir = makeTmpDir();
     const path = join(dir, "sub", "config.json");

src/data/config.ts

@@ -62,13 +62,15 @@ export function isProviderEnabled(config: BotConfig, platform: string): boolean
 
 /**
  * The default platform for !play/!add/!playlist/!album and all REST/WebUI calls:
- * jellyfin when enabled, otherwise the first enabled provider in a fixed
- * priority order. Falls back to "netease" when nothing is enabled so callers
- * always get a provider — the enabled-gate then produces the friendly error.
+ * the first enabled provider in a fixed priority order (netease with the default
+ * config; jellyfin ranks after the online music platforms because it is an
+ * opt-in source, but ahead of the video sites for users who run it as their
+ * only music library). Falls back to "netease" when nothing is enabled so
+ * callers always get a provider — the enabled-gate then produces the friendly
+ * error.
  */
 export function defaultPlatform(config: BotConfig): GateableProvider {
-  if (config.enabledProviders.includes("jellyfin")) return "jellyfin";
-  for (const p of ["netease", "qq", "kugou", "bilibili", "youtube"] as const) {
+  for (const p of ["netease", "qq", "kugou", "jellyfin", "bilibili", "youtube"] as const) {
     if (config.enabledProviders.includes(p)) return p;
   }
   return "netease";
@@ -102,9 +104,10 @@ export interface BotConfig {
   jellyfin: JellyfinConfig;
   /**
    * Which gateable providers are active (see GATEABLE_PROVIDERS). Default is
-   * jellyfin-only: the legacy NetEase/QQ/Bilibili/YouTube/Kugou sources keep
-   * compiling but stay disabled — their embedded sidecar API servers must not
-   * start (or bind ports 3001/3200) unless listed here.
+   * the online sources (NetEase/QQ/Bilibili/YouTube/Kugou); jellyfin is an
+   * opt-in extra that must be listed here (Settings → Jellyfin 音乐库 toggles
+   * it). Sources not listed stay disabled — the NetEase/QQ embedded sidecar
+   * API servers must not start (or bind ports 3001/3200) unless enabled.
    */
   enabledProviders: GateableProvider[];
 }
@@ -159,7 +162,7 @@ export function getDefaultConfig(): BotConfig {
       apiKey: "",
       userId: "",
     },
-    enabledProviders: ["jellyfin"],
+    enabledProviders: ["netease", "qq", "bilibili", "youtube", "kugou"],
   };
 }
 
@@ -306,8 +309,8 @@ export function loadConfig(path: string): BotConfig {
     };
 
     // enabledProviders → known providers only; a non-array falls back to the
-    // default (["jellyfin"]). An explicitly-empty array is respected (operator
-    // chose to disable every gateable source).
+    // default (online sources, jellyfin off). An explicitly-empty array is
+    // respected (operator chose to disable every gateable source).
     const enabledProviders = Array.isArray(partial.enabledProviders)
       ? partial.enabledProviders.filter((p): p is GateableProvider =>
           (GATEABLE_PROVIDERS as readonly string[]).includes(p as string),

src/index.ts

@@ -56,8 +56,8 @@ async function main() {
     {
       neteasePort: config.neteaseApiPort,
       qqMusicPort: config.qqMusicApiPort,
-      // Provider gating: with the default (jellyfin-only) config, neither
-      // sidecar starts and ports 3001/3200 are never bound.
+      // Provider gating: a sidecar only starts (and binds 3001/3200) when its
+      // source is listed in enabledProviders — both are on in the default config.
       neteaseEnabled: isProviderEnabled(config, "netease"),
       qqEnabled: isProviderEnabled(config, "qq"),
     },

src/web/api/bot.test.ts

@@ -612,7 +612,8 @@ describe("bot router /settings jellyfin block + enabledProviders", () => {
       hasPassword: true,
       hasApiKey: false,
     });
-    expect(res.body.enabledProviders).toEqual(["jellyfin"]);
+    // Default: online sources on, jellyfin opt-in (not listed).
+    expect(res.body.enabledProviders).toEqual(["netease", "qq", "bilibili", "youtube", "kugou"]);
   });
 
   it("POST /settings merges jellyfin, keeps stored secrets on blank, hot-configures", async () => {

src/web/api/music.test.ts

@@ -82,44 +82,51 @@ describe("music router provider gating (enabledProviders) + jellyfin endpoints",
     return { app, netease, jellyfin };
   }
 
-  it("routes a platform-less /search to the default platform (jellyfin)", async () => {
+  it("routes a platform-less /search to the default platform (netease)", async () => {
     const { app, netease, jellyfin } = mount(getDefaultConfig());
     const res = await request(app).get("/api/music/search?q=hello");
     expect(res.status).toBe(200);
-    expect(jellyfin.search).toHaveBeenCalledWith("hello", 20, 0);
-    expect(netease.search).not.toHaveBeenCalled();
+    expect(netease.search).toHaveBeenCalledWith("hello", 20, 0);
+    expect(jellyfin.search).not.toHaveBeenCalled();
   });
 
   it("rejects a disabled platform with 400 without calling its provider", async () => {
-    // Default config enables jellyfin only.
-    const { app, netease } = mount(getDefaultConfig());
-    const res = await request(app).get("/api/music/search?q=hello&platform=netease");
+    // Default config leaves jellyfin (opt-in) disabled.
+    const { app, jellyfin } = mount(getDefaultConfig());
+    const res = await request(app).get("/api/music/search?q=hello&platform=jellyfin");
     expect(res.status).toBe(400);
-    expect(netease.search).not.toHaveBeenCalled();
+    expect(jellyfin.search).not.toHaveBeenCalled();
   });
 
-  it("allows an explicitly re-enabled legacy platform", async () => {
+  it("allows an explicitly enabled jellyfin platform", async () => {
     const config = getDefaultConfig();
-    config.enabledProviders = ["jellyfin", "netease"];
-    const { app, netease } = mount(config);
-    const res = await request(app).get("/api/music/search?q=hello&platform=netease");
+    config.enabledProviders = [...config.enabledProviders, "jellyfin"];
+    const { app, jellyfin } = mount(config);
+    const res = await request(app).get("/api/music/search?q=hello&platform=jellyfin");
     expect(res.status).toBe(200);
-    expect(netease.search).toHaveBeenCalledWith("hello", 20, 0);
+    expect(jellyfin.search).toHaveBeenCalledWith("hello", 20, 0);
   });
 
   it("GET /providers reports enabled sources and the default platform", async () => {
     const { app } = mount(getDefaultConfig());
     const res = await request(app).get("/api/music/providers");
     expect(res.status).toBe(200);
-    expect(res.body.default).toBe("jellyfin");
-    expect(res.body.enabled).toContain("jellyfin");
+    expect(res.body.default).toBe("netease");
+    expect(res.body.enabled).toContain("netease");
     expect(res.body.enabled).toContain("local"); // localAudioEnabled defaults on
-    expect(res.body.enabled).not.toContain("netease");
+    expect(res.body.enabled).not.toContain("jellyfin"); // opt-in, off by default
     expect(res.body.enabled).not.toContain("spotify"); // spotify.enabled defaults off
   });
 
+  /** Default config plus the opt-in jellyfin source enabled. */
+  function configWithJellyfin() {
+    const config = getDefaultConfig();
+    config.enabledProviders = [...config.enabledProviders, "jellyfin"];
+    return config;
+  }
+
   it("GET /jellyfin/latest-albums returns provider data", async () => {
-    const { app, jellyfin } = mount(getDefaultConfig());
+    const { app, jellyfin } = mount(configWithJellyfin());
     const res = await request(app).get("/api/music/jellyfin/latest-albums?limit=5");
     expect(res.status).toBe(200);
     expect(
@@ -128,16 +135,14 @@ describe("music router provider gating (enabledProviders) + jellyfin endpoints",
     expect(res.body.albums).toHaveLength(1);
   });
 
-  it("GET /jellyfin/latest-albums is 400 when jellyfin is disabled", async () => {
-    const config = getDefaultConfig();
-    config.enabledProviders = ["netease"];
-    const { app } = mount(config);
+  it("GET /jellyfin/latest-albums is 400 when jellyfin is disabled (the default)", async () => {
+    const { app } = mount(getDefaultConfig());
     const res = await request(app).get("/api/music/jellyfin/latest-albums");
     expect(res.status).toBe(400);
   });
 
   it("GET /jellyfin/favorites denies unauthenticated/guest access", async () => {
-    const { app } = mount(getDefaultConfig());
+    const { app } = mount(configWithJellyfin());
     const res = await request(app).get("/api/music/jellyfin/favorites");
     expect(res.status).toBe(401);
   });

src/web/api/music.ts

@@ -37,9 +37,10 @@ export function createMusicRouter(
 
   /**
    * Provider gating for user-supplied platform params. No platform → the
-   * configured default (jellyfin unless disabled). A disabled platform gets a
-   * friendly 400 and null back — the handler must return immediately.
-   * Without a config (unit-test routers), everything stays enabled.
+   * configured default (see defaultPlatform(); netease in the default config).
+   * A disabled platform gets a friendly 400 and null back — the handler must
+   * return immediately. Without a config (unit-test routers), everything
+   * stays enabled.
    */
   function resolveProvider(platform: unknown, res: Response): MusicProvider | null {
     const requested = typeof platform === "string" && platform ? platform : undefined;
@@ -144,7 +145,8 @@ export function createMusicRouter(
       // view would only yield results that get skipped. Spotify search remains
       // available from its own tab via /search?platform=spotify.
       // Provider gating (#enabledProviders): disabled sources are skipped, not
-      // searched. Jellyfin — the primary source — leads the merged results.
+      // searched. Jellyfin (an opt-in source) leads the merged results when
+      // enabled — a self-hosted library match is almost always the wanted one.
       const enabled = (p: string) => !config || isProviderEnabled(config, p);
       const none = { songs: [], albums: [], playlists: [] };
       const [jellyfinResult, neteaseResult, qqResult, bilibiliResult, localResult, kugouResult] = await Promise.allSettled([