spotifify 0.1.1

package/src/sources/local/source.ts

@@ -0,0 +1,105 @@
+import { basename, extname } from "node:path";
+import type { Config } from "../../config.ts";
+import type { SourceTrackRow } from "../../state/repo.ts";
+import { hashFile } from "../../util/fs.ts";
+import { log } from "../../util/log.ts";
+import { mapLimit } from "../../util/retry.ts";
+import type { Source, SourcePlaylist, SourceTrack } from "../types.ts";
+import { readNcmMeta } from "./ncm.ts";
+import { scanDirs, type ScannedFile } from "./scan.ts";
+import { parseFilename, readTags, type FileTags } from "./tags.ts";
+
+export const LOCAL_LIBRARY_ID = "library";
+
+const CONCURRENCY = 8;
+
+type Described = Pick<SourceTrack, "title" | "artists" | "album" | "durationMs" | "isrc" | "neteaseId" | "aliases">;
+
+async function describe(path: string, pattern: Config["local"]["filename_pattern"]): Promise<Described> {
+  if (extname(path).toLowerCase() === ".ncm") {
+    const m = await readNcmMeta(path);
+    return {
+      title: m.musicName,
+      artists: m.artist.map(([name]) => name),
+      album: m.album || undefined,
+      durationMs: m.duration,
+      // 0 shows up in NCMs of locally-uploaded songs; it is not a real song id
+      neteaseId: m.musicId > 0 ? m.musicId : undefined,
+      aliases: [...(m.alias ?? []), ...(m.transNames ?? [])],
+    };
+  }
+  let tags: FileTags;
+  try {
+    tags = await readTags(path);
+  } catch (e) {
+    // Odd containers (fragmented m4a, truncated files) still deserve a best-effort entry from the file name.
+    log.debug(`tags unreadable, using file name: ${path}`, { error: e instanceof Error ? e.message : String(e) });
+    tags = { artists: [] };
+  }
+  const ne = tags.netease;
+  if (ne && ne.musicId > 0) {
+    // NetEase download with its "163 key" comment: the song id makes it share a canonical key with the playlist track.
+    return {
+      title: tags.title || ne.musicName,
+      artists: tags.artists.length > 0 ? splitNeteaseArtists(tags.artists) : ne.artist.map(([name]) => name),
+      album: tags.album || ne.album || undefined,
+      durationMs: tags.durationMs ?? ne.duration,
+      isrc: tags.isrc,
+      neteaseId: ne.musicId,
+      aliases: [...(ne.alias ?? []), ...(ne.transNames ?? [])],
+    };
+  }
+  let title = tags.title;
+  let artists = tags.artists;
+  if (title === undefined || artists.length === 0) {
+    const fromName = parseFilename(basename(path, extname(path)), pattern);
+    title ??= fromName.title;
+    if (artists.length === 0) artists = fromName.artists;
+  }
+  return { title, artists, album: tags.album, durationMs: tags.durationMs, isrc: tags.isrc, aliases: [] };
+}
+
+/** The NetEase client writes all artists into one tag joined by "/" (e.g. "DECO*27/初音ミク"). */
+function splitNeteaseArtists(artists: string[]): string[] {
+  return artists.flatMap((a) => a.split("/")).map((a) => a.trim()).filter((a) => a !== "");
+}
+
+/** Every configured directory merged into a single fixed playlist, tracks in absolute-path order. */
+export class LocalSource implements Source {
+  readonly kind = "local" as const;
+
+  constructor(
+    private readonly cfg: Config["local"],
+    /** previous pull keyed by absolute path (repo.localTracksByPath()); unchanged (size, mtime) skips hashing and tag reads */
+    private readonly cache: Map<string, SourceTrackRow>,
+    private readonly onProgress?: (done: number, total: number) => void,
+  ) {}
+
+  async pull(): Promise<{ playlists: Array<{ playlist: SourcePlaylist; tracks: SourceTrack[] }> }> {
+    const files = await scanDirs(this.cfg.dirs, this.cfg.extensions);
+    let done = 0;
+    const tracks = await mapLimit(files, CONCURRENCY, async (file) => {
+      const track = await this.track(file);
+      this.onProgress?.(++done, files.length);
+      return track;
+    });
+    const playlist: SourcePlaylist = { kind: "local", externalId: LOCAL_LIBRARY_ID, name: this.cfg.playlist_name };
+    return { playlists: [{ playlist, tracks: tracks.filter((t) => t !== null) }] };
+  }
+
+  private async track(file: ScannedFile): Promise<SourceTrack | null> {
+    const cached = this.cache.get(file.path);
+    if (cached?.file !== undefined && cached.file.size === file.size && cached.file.mtimeMs === file.mtimeMs) {
+      const { id: _id, canonicalKey: _key, lastSeenAt: _seen, ...track } = cached;
+      return track;
+    }
+    try {
+      const contentHash = await hashFile(file.path);
+      const meta = await describe(file.path, this.cfg.filename_pattern);
+      return { kind: "local", externalId: file.path, ...meta, file: { path: file.path, contentHash, size: file.size, mtimeMs: file.mtimeMs } };
+    } catch (e) {
+      log.warn(`skipping unreadable file ${file.path}: ${e instanceof Error ? e.message : String(e)}`);
+      return null;
+    }
+  }
+}

package/src/sources/local/tags.ts

@@ -0,0 +1,67 @@
+import { parseFile, type IAudioMetadata } from "music-metadata";
+import { decode163Key, type NcmMeta } from "./ncm.ts";
+
+export interface FileTags {
+  title?: string;
+  artists: string[];
+  album?: string;
+  durationMs?: number;
+  isrc?: string;
+  /** decoded `163 key(Don't modify):…` comment written by the NetEase client into mp3/flac/m4a downloads */
+  netease?: NcmMeta;
+}
+
+export async function readTags(path: string): Promise<FileTags> {
+  // The cheap header-only pass covers most formats; only scan the whole file when duration is still unknown.
+  let meta = await parseFile(path, { skipCovers: true });
+  if (meta.format.duration === undefined) meta = await parseFile(path, { skipCovers: true, duration: true });
+  const { common, format } = meta;
+  const artists = (common.artists ?? (common.artist === undefined ? [] : [common.artist])).map((a) => a.trim()).filter((a) => a !== "");
+  const isrc = common.isrc?.[0]?.replace(/[^0-9A-Za-z]/g, "").toUpperCase();
+  return {
+    title: common.title?.trim() || undefined,
+    artists,
+    album: common.album?.trim() || undefined,
+    durationMs: format.duration === undefined ? undefined : Math.round(format.duration * 1000),
+    isrc: isrc !== undefined && isrc.length === 12 ? isrc : undefined,
+    netease: findNeteaseKey(meta, path),
+  };
+}
+
+/** The NetEase key lives in ID3 COMM (mp3), Vorbis DESCRIPTION/COMMENT (flac/ogg) or ©cmt (m4a); music-metadata folds most into `common.comment`. */
+function findNeteaseKey(meta: IAudioMetadata, path: string): NcmMeta | undefined {
+  const texts: string[] = [];
+  for (const c of meta.common.comment ?? []) {
+    const text = typeof c === "string" ? c : c.text;
+    if (text) texts.push(text);
+  }
+  for (const tags of Object.values(meta.native)) {
+    for (const t of tags) {
+      if (!/^(DESCRIPTION|COMMENT|COMM|TXXX:comment|©cmt)$/i.test(t.id)) continue;
+      const v = t.value as unknown;
+      if (typeof v === "string") texts.push(v);
+      else if (typeof v === "object" && v !== null && "text" in v && typeof v.text === "string") texts.push(v.text);
+    }
+  }
+  for (const text of texts) {
+    const m = decode163Key(text, path);
+    if (m) return m;
+  }
+  return undefined;
+}
+
+/** Leading track numbers: `01. `, `01.`, `01 - `, `1 - ` (a dot must not be followed by another digit, e.g. `1.5 - x`). */
+const TRACK_NO = /^\d{1,3}(?:\.(?!\d)\s*|\s*-\s+)/;
+/** First ` - ` (or en/em dash) surrounded by whitespace splits the two halves. */
+const SEPARATOR = /^(.*?)\s+[-\u2013\u2014]\s+(.*)$/;
+const ARTIST_SEP = /[/、;&,]/;
+
+export function parseFilename(basenameWithoutExt: string, pattern: "artist-title" | "title-artist"): { title: string; artists: string[] } {
+  const name = basenameWithoutExt.replace(TRACK_NO, "").trim();
+  const m = SEPARATOR.exec(name);
+  if (!m) return { title: name, artists: [] };
+  const left = m[1]!.trim();
+  const right = m[2]!.trim();
+  const [artistPart, title] = pattern === "artist-title" ? [left, right] : [right, left];
+  return { title, artists: artistPart.split(ARTIST_SEP).map((a) => a.trim()).filter((a) => a !== "") };
+}

package/src/sources/netease/auth.ts

@@ -0,0 +1,91 @@
+import { login_qr_check, login_qr_create, login_qr_key } from "./lib.ts";
+import { z } from "zod";
+import { log } from "../../util/log.ts";
+import { sleep } from "../../util/retry.ts";
+
+const QrKeyRes = z.object({ body: z.object({ data: z.object({ unikey: z.string().min(1) }) }) });
+const QrCreateRes = z.object({ body: z.object({ data: z.object({ qrurl: z.string().min(1) }) }) });
+const QrCheckRes = z.object({ body: z.object({ code: z.number().optional(), message: z.string().optional(), cookie: z.string().optional() }) });
+
+const QR_EXPIRED = 800;
+const QR_WAITING = 801;
+const QR_SCANNED = 802;
+const QR_CONFIRMED = 803;
+
+/**
+ * QR login: renders the login URL via `render`, then polls until the user confirms on the phone.
+ * Resolves the cookie header string (`MUSIC_U=...; __csrf=...`).
+ */
+export async function loginByQr(render: (qrUrl: string) => void, opts: { timeoutMs?: number; pollMs?: number } = {}): Promise<string> {
+  const timeoutMs = opts.timeoutMs ?? 120_000;
+  const pollMs = opts.pollMs ?? 2000;
+
+  const keyRes = QrKeyRes.safeParse(await login_qr_key({}));
+  if (!keyRes.success) throw new Error("netease login_qr_key returned no unikey");
+  const key = keyRes.data.body.data.unikey;
+
+  const createRes = QrCreateRes.safeParse(await login_qr_create({ key, qrimg: false }));
+  if (!createRes.success) throw new Error("netease login_qr_create returned no qrurl");
+  render(createRes.data.body.data.qrurl);
+
+  const deadline = Date.now() + timeoutMs;
+  let scannedLogged = false;
+  while (true) {
+    await sleep(pollMs);
+    if (Date.now() > deadline) throw new Error(`netease QR login timed out after ${timeoutMs} ms`);
+    let raw: unknown;
+    try {
+      raw = await login_qr_check({ key });
+    } catch (e) {
+      // the library's own catch path throws a ReferenceError on network failure; keep polling until the deadline
+      log.debug("netease login_qr_check failed, retrying", { error: e instanceof Error ? e.message : String(e) });
+      continue;
+    }
+    const check = QrCheckRes.safeParse(raw);
+    if (!check.success) throw new Error("netease login_qr_check returned an unexpected response");
+    const body = check.data.body;
+    switch (body.code) {
+      case QR_EXPIRED:
+        throw new Error("netease QR code expired; run the login again");
+      case QR_WAITING:
+        continue;
+      case QR_SCANNED:
+        if (!scannedLogged) {
+          log.info("netease QR scanned; confirm on your phone");
+          scannedLogged = true;
+        }
+        continue;
+      case QR_CONFIRMED: {
+        const cookie = normalizeCookie(body.cookie ?? "");
+        if (!cookie.includes("MUSIC_U=")) throw new Error("netease QR login confirmed but no MUSIC_U cookie was returned");
+        return cookie;
+      }
+      default:
+        throw new Error(`netease login_qr_check unexpected code ${body.code ?? "?"}${body.message ? `: ${body.message}` : ""}`);
+    }
+  }
+}
+
+const COOKIE_ATTRIBUTE = /^(Max-Age|Expires|Path|Domain|HTTPOnly|Secure|SameSite)$/i;
+
+/**
+ * Accepts "MUSIC_U=xxx", a full Cookie header, or the `;`-joined Set-Cookie list returned by login_qr_check.
+ * Returns a `k=v; k2=v2` header. When MUSIC_U is present, only MUSIC_U (+ __csrf if present) are kept.
+ */
+export function normalizeCookie(raw: string): string {
+  const pairs: Array<[string, string]> = [];
+  for (const part of raw.split(/;\s*/)) {
+    const eq = part.indexOf("=");
+    if (eq <= 0) continue;
+    const k = part.slice(0, eq).trim();
+    const v = part.slice(eq + 1).trim();
+    if (!k || !v || COOKIE_ATTRIBUTE.test(k)) continue;
+    pairs.push([k, v]);
+  }
+  const musicU = pairs.find(([k]) => k === "MUSIC_U");
+  if (musicU) {
+    const csrf = pairs.find(([k]) => k === "__csrf");
+    return csrf ? `MUSIC_U=${musicU[1]}; __csrf=${csrf[1]}` : `MUSIC_U=${musicU[1]}`;
+  }
+  return pairs.map(([k, v]) => `${k}=${v}`).join("; ");
+}

package/src/sources/netease/client.ts

@@ -0,0 +1,188 @@
+import { login_status, playlist_detail, song_detail, user_playlist } from "./lib.ts";
+import { z } from "zod";
+import { log } from "../../util/log.ts";
+import { chunk, RetryableError, sleep, withRetry } from "../../util/retry.ts";
+
+export interface NeteasePlaylistSummary {
+  id: number;
+  name: string;
+  creatorId: number;
+  specialType: number;
+  trackCount: number;
+  updateTime: number;
+  trackUpdateTime: number;
+}
+
+export interface NeteaseSong {
+  id: number;
+  name: string;
+  artists: string[];
+  album: string;
+  durationMs: number;
+  aliases: string[];
+}
+
+/** Cookie invalid / expired: the CLI exits 3 without doing anything else. */
+export class NeteaseAuthError extends Error {
+  constructor(message = "netease login required (cookie missing or expired)") {
+    super(message);
+    this.name = "NeteaseAuthError";
+  }
+}
+
+// Response bodies as observed from NeteaseCloudMusicApi 4.32.0. The library resolves `{ status, body }` and
+// *rejects* with the same plain-object shape (not an Error) whenever the API code is not 200 / a special code.
+const LoginStatusBody = z.object({
+  data: z.object({ profile: z.object({ userId: z.number(), nickname: z.string().default("") }).nullish() }).optional(),
+});
+const UserPlaylistBody = z.object({
+  more: z.boolean().default(false),
+  playlist: z
+    .array(
+      z.object({
+        id: z.number(),
+        name: z.string(),
+        creator: z.object({ userId: z.number() }).nullish(),
+        userId: z.number().optional(),
+        specialType: z.number().default(0),
+        trackCount: z.number().default(0),
+        updateTime: z.number().default(0),
+        trackUpdateTime: z.number().optional(),
+      }),
+    )
+    .default([]),
+});
+const PlaylistDetailBody = z.object({
+  playlist: z.object({
+    trackIds: z.array(z.object({ id: z.number() })).default([]),
+    updateTime: z.number().default(0),
+    trackUpdateTime: z.number().optional(),
+  }),
+});
+// Cloud-disk uploads (and some delisted songs) carry null `name` / `ar[].name` / `al.name`; uploads keep the
+// original file metadata under `pc` (sn = title, ar = artist, alb = album).
+const SongDetailBody = z.object({
+  songs: z
+    .array(
+      z.object({
+        id: z.number(),
+        name: z.string().nullish(),
+        ar: z.array(z.object({ name: z.string().nullish() })).nullish(),
+        al: z.object({ name: z.string().nullish() }).nullish(),
+        dt: z.number().nullish(),
+        alia: z.array(z.string().nullish()).nullish(),
+        tns: z.array(z.string().nullish()).nullish(),
+        pc: z.object({ sn: z.string().nullish(), ar: z.string().nullish(), alb: z.string().nullish() }).nullish(),
+      }),
+    )
+    .default([]),
+});
+const Failure = z.object({
+  status: z.number().optional(),
+  body: z.object({ code: z.number().optional(), msg: z.string().optional(), message: z.string().optional() }).optional(),
+});
+const Envelope = z.object({ status: z.number(), body: z.object({ code: z.number().optional() }).passthrough() });
+
+export const REQUEST_GAP_MS = 200;
+const SONG_DETAIL_BATCH = 500;
+const PLAYLIST_PAGE = 1000;
+
+/** Normalizes a library rejection (plain object) or thrown Error into our error taxonomy. */
+function toError(e: unknown): Error {
+  if (e instanceof Error) {
+    // the library routes network failures into status-502 objects; a genuine throw is a client-side transport fault
+    return new RetryableError(`netease request failed: ${e.message}`);
+  }
+  const parsed = Failure.safeParse(e);
+  const f = parsed.success ? parsed.data : {};
+  const status = f.status ?? 0;
+  const code = f.body?.code ?? status;
+  const msg = f.body?.msg ?? f.body?.message ?? "";
+  if (code === 301 || status === 301 || msg.includes("需要登录")) return new NeteaseAuthError();
+  if (status >= 500 || code >= 500) return new RetryableError(`netease upstream error ${code}${msg ? `: ${msg}` : ""}`);
+  return new Error(`netease api error ${code}${msg ? `: ${msg}` : ""}`);
+}
+
+async function call<S extends z.ZodType>(what: string, schema: S, fn: () => Promise<unknown>): Promise<z.infer<S>> {
+  return withRetry(async () => {
+    let raw: unknown;
+    try {
+      raw = await fn();
+    } catch (e) {
+      throw toError(e);
+    }
+    const env = Envelope.safeParse(raw);
+    if (!env.success) throw new Error(`netease ${what}: unexpected response envelope`);
+    const code = env.data.body.code;
+    if (code !== undefined && code !== 200) throw toError(env.data);
+    const body = schema.safeParse(env.data.body);
+    if (!body.success) throw new Error(`netease ${what}: unexpected body shape: ${body.error.message}`);
+    return body.data;
+  });
+}
+
+export class NeteaseClient {
+  constructor(private readonly cookie: string) {}
+
+  async loginStatus(): Promise<{ uid: number; nickname: string } | null> {
+    const body = await call("login_status", LoginStatusBody, () => login_status({ cookie: this.cookie }));
+    const profile = body.data?.profile;
+    return profile ? { uid: profile.userId, nickname: profile.nickname } : null;
+  }
+
+  async userPlaylists(uid: number): Promise<NeteasePlaylistSummary[]> {
+    const out: NeteasePlaylistSummary[] = [];
+    for (let offset = 0; ; offset += PLAYLIST_PAGE) {
+      if (offset > 0) await sleep(REQUEST_GAP_MS);
+      const body = await call("user_playlist", UserPlaylistBody, () => user_playlist({ cookie: this.cookie, uid, limit: PLAYLIST_PAGE, offset }));
+      for (const p of body.playlist) {
+        out.push({
+          id: p.id,
+          name: p.name,
+          creatorId: p.creator?.userId ?? p.userId ?? -1,
+          specialType: p.specialType,
+          trackCount: p.trackCount,
+          updateTime: p.updateTime,
+          trackUpdateTime: p.trackUpdateTime ?? p.updateTime,
+        });
+      }
+      if (!body.more || body.playlist.length === 0) return out;
+    }
+  }
+
+  async playlistTrackIds(id: number): Promise<{ ids: number[]; updateTime: number; trackUpdateTime: number }> {
+    const body = await call("playlist_detail", PlaylistDetailBody, () => playlist_detail({ cookie: this.cookie, id }));
+    const pl = body.playlist;
+    return { ids: pl.trackIds.map((t) => t.id), updateTime: pl.updateTime, trackUpdateTime: pl.trackUpdateTime ?? pl.updateTime };
+  }
+
+  /** Fetches song metadata in serial batches of 500 with a 200 ms gap; output order follows `ids`. */
+  async songDetails(ids: number[]): Promise<NeteaseSong[]> {
+    const byId = new Map<number, NeteaseSong>();
+    const batches = chunk(ids, SONG_DETAIL_BATCH);
+    for (let i = 0; i < batches.length; i++) {
+      if (i > 0) await sleep(REQUEST_GAP_MS);
+      const batch = batches[i]!;
+      const body = await call("song_detail", SongDetailBody, () => song_detail({ cookie: this.cookie, ids: batch.join(",") }));
+      for (const s of body.songs) {
+        const artists = (s.ar ?? []).map((a) => a.name ?? "").filter((n) => n.length > 0);
+        if (artists.length === 0 && s.pc?.ar) artists.push(s.pc.ar);
+        byId.set(s.id, {
+          id: s.id,
+          name: s.name || s.pc?.sn || "",
+          artists,
+          album: s.al?.name || s.pc?.alb || "",
+          durationMs: s.dt ?? 0,
+          aliases: [...(s.alia ?? []), ...(s.tns ?? [])].filter((a): a is string => typeof a === "string" && a.length > 0),
+        });
+      }
+      log.debug("netease song_detail", { batch: i + 1, of: batches.length, requested: batch.length, got: body.songs.length });
+    }
+    const out: NeteaseSong[] = [];
+    for (const id of ids) {
+      const s = byId.get(id);
+      if (s) out.push(s);
+    }
+    return out;
+  }
+}

package/src/sources/netease/lib.ts

@@ -0,0 +1,38 @@
+/**
+ * Bundle-safe entry to NeteaseCloudMusicApi. Its `main.js` discovers endpoints with
+ * `readdirSync(__dirname/module)` + dynamic `require` at load time, which only works with node_modules on
+ * disk and breaks inside a compiled binary. The endpoint modules are plain `(query, request) => …`
+ * functions, so load the ones we use explicitly and reproduce main.js's cookie handling here.
+ *
+ * `util/request.js` reads `<tmpdir>/anonymous_token` synchronously while loading and throws when it is
+ * missing (main.js normally creates it). Bun evaluates CommonJS dependencies before any ESM module body
+ * runs, so a side-effect `import` cannot create the file first; the modules are pulled in with `require`
+ * after the file exists. The string-literal requires are still bundled statically by `bun build`.
+ */
+import { existsSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+const anonymousTokenPath = join(tmpdir(), "anonymous_token");
+if (!existsSync(anonymousTokenPath)) writeFileSync(anonymousTokenPath, "", "utf-8");
+
+const request = require("NeteaseCloudMusicApi/util/request.js") as NeteaseApi.Request;
+const { cookieToJson } = require("NeteaseCloudMusicApi/util/index.js") as { cookieToJson: (cookie: string) => Record<string, string> };
+const asModule = (m: unknown): NeteaseApi.Module => m as NeteaseApi.Module;
+
+export type NeteaseApiCall = (data?: Record<string, unknown>) => Promise<unknown>;
+
+function wrap(mod: NeteaseApi.Module): NeteaseApiCall {
+  return (data = {}) => {
+    const cookie = typeof data.cookie === "string" ? cookieToJson(data.cookie) : (data.cookie ?? {});
+    return mod({ ...data, cookie }, request);
+  };
+}
+
+export const login_status = wrap(asModule(require("NeteaseCloudMusicApi/module/login_status.js")));
+export const user_playlist = wrap(asModule(require("NeteaseCloudMusicApi/module/user_playlist.js")));
+export const playlist_detail = wrap(asModule(require("NeteaseCloudMusicApi/module/playlist_detail.js")));
+export const song_detail = wrap(asModule(require("NeteaseCloudMusicApi/module/song_detail.js")));
+export const login_qr_key = wrap(asModule(require("NeteaseCloudMusicApi/module/login_qr_key.js")));
+export const login_qr_create = wrap(asModule(require("NeteaseCloudMusicApi/module/login_qr_create.js")));
+export const login_qr_check = wrap(asModule(require("NeteaseCloudMusicApi/module/login_qr_check.js")));

package/src/sources/netease/source.ts

@@ -0,0 +1,91 @@
+import type { Config } from "../../config.ts";
+import { log } from "../../util/log.ts";
+import type { Source, SourceKind, SourcePlaylist, SourceTrack } from "../types.ts";
+import { NeteaseAuthError, NeteaseClient, type NeteasePlaylistSummary, type NeteaseSong } from "./client.ts";
+
+/** Read-only view of previously pulled netease state (backed by the repo) used to skip unchanged playlists / known songs. */
+export interface NeteaseCache {
+  /** `sourceUpdatedAt` stored for the playlist on the last pull, undefined if never pulled */
+  playlistUpdatedAt(externalId: string): number | undefined;
+  /** tracks in stored position order; empty when unknown */
+  playlistTracks(externalId: string): SourceTrack[];
+  /** already-known songs keyed by externalId (netease song id as string) */
+  knownSongs(externalIds: string[]): Map<string, SourceTrack>;
+}
+
+/** netease `specialType` of the user's own "我喜欢的音乐" playlist */
+const LIKED_SPECIAL_TYPE = 5;
+
+function toSourceTrack(s: NeteaseSong): SourceTrack {
+  return {
+    kind: "netease",
+    externalId: String(s.id),
+    title: s.name,
+    artists: s.artists,
+    album: s.album || undefined,
+    durationMs: s.durationMs || undefined,
+    neteaseId: s.id,
+    aliases: s.aliases,
+  };
+}
+
+export class NeteaseSource implements Source {
+  readonly kind: SourceKind = "netease";
+
+  constructor(
+    private readonly client: NeteaseClient,
+    private readonly cfg: Config["netease"],
+    private readonly cache: NeteaseCache,
+  ) {}
+
+  async pull(): Promise<{ playlists: Array<{ playlist: SourcePlaylist; tracks: SourceTrack[] }> }> {
+    const me = await this.client.loginStatus();
+    if (!me) throw new NeteaseAuthError();
+    log.info("netease logged in", { uid: me.uid, nickname: me.nickname });
+
+    const excluded = new Set(this.cfg.exclude_playlists);
+    const included = new Set(this.cfg.include_playlists);
+    const selected = (p: NeteasePlaylistSummary) => {
+      const liked = p.specialType === LIKED_SPECIAL_TYPE;
+      if (liked && !this.cfg.include_liked) return false;
+      if (excluded.has(p.name) || excluded.has(String(p.id))) return false;
+      if (included.size === 0) return true;
+      return included.has(p.name) || included.has(String(p.id)) || (liked && included.has("liked"));
+    };
+    const summaries = (await this.client.userPlaylists(me.uid)).filter((p) => p.creatorId === me.uid && selected(p));
+
+    const playlists: Array<{ playlist: SourcePlaylist; tracks: SourceTrack[] }> = [];
+    for (const summary of summaries) {
+      const externalId = String(summary.id);
+      const playlist: SourcePlaylist = { kind: "netease", externalId, name: summary.name, sourceUpdatedAt: summary.trackUpdateTime };
+
+      if (this.cache.playlistUpdatedAt(externalId) === summary.trackUpdateTime) {
+        const cached = this.cache.playlistTracks(externalId);
+        if (cached.length > 0 || summary.trackCount === 0) {
+          log.info("netease playlist unchanged", { name: summary.name, tracks: cached.length });
+          playlists.push({ playlist, tracks: cached });
+          continue;
+        }
+      }
+
+      const detail = await this.client.playlistTrackIds(summary.id);
+      const ids = detail.ids.map(String);
+      const known = this.cache.knownSongs(ids);
+      const missing = detail.ids.filter((id) => !known.has(String(id)));
+      const fetched = new Map<string, SourceTrack>();
+      if (missing.length > 0) {
+        for (const song of await this.client.songDetails(missing)) fetched.set(String(song.id), toSourceTrack(song));
+      }
+
+      const tracks: SourceTrack[] = [];
+      for (const id of ids) {
+        const t = known.get(id) ?? fetched.get(id);
+        if (t) tracks.push(t);
+        else log.warn("netease song_detail omitted a track", { playlist: summary.name, id });
+      }
+      log.info("netease playlist pulled", { name: summary.name, tracks: tracks.length, fetched: fetched.size, cached: known.size });
+      playlists.push({ playlist, tracks });
+    }
+    return { playlists };
+  }
+}

package/src/sources/types.ts

@@ -0,0 +1,49 @@
+export type SourceKind = "netease" | "local";
+
+export interface SourcePlaylist {
+  kind: SourceKind;
+  /** netease playlist id, or the fixed "library" id for the local source */
+  externalId: string;
+  name: string;
+  /** source-side modification time (ms); undefined when the source cannot report one */
+  sourceUpdatedAt?: number;
+}
+
+export interface SourceTrack {
+  kind: SourceKind;
+  /** netease song id, or the absolute file path for local tracks */
+  externalId: string;
+  title: string;
+  artists: string[];
+  album?: string;
+  durationMs?: number;
+  isrc?: string;
+  /** known for netease-source tracks and for .ncm files (header musicId) */
+  neteaseId?: number;
+  /** alternative titles: netease `alia`/`tns`, ncm `alias`/`transNames` */
+  aliases: string[];
+  file?: {
+    path: string;
+    /** blake2b256 of the file as stored on disk (encrypted bytes for .ncm) */
+    contentHash: string;
+    size: number;
+    mtimeMs: number;
+  };
+}
+
+/**
+ * Identity under which match decisions are shared across sources.
+ * Priority: netease id > ISRC > file content hash.
+ */
+export function canonicalKey(t: SourceTrack): string {
+  if (t.neteaseId !== undefined) return `netease:${t.neteaseId}`;
+  if (t.isrc) return `isrc:${t.isrc.toUpperCase()}`;
+  if (t.file) return `local:${t.file.contentHash}`;
+  throw new Error(`track ${t.kind}:${t.externalId} has no identity (no neteaseId, isrc, or file)`);
+}
+
+/** Pull one source into canonical playlists + ordered tracks. Implementations must be side-effect free. */
+export interface Source {
+  readonly kind: SourceKind;
+  pull(): Promise<{ playlists: Array<{ playlist: SourcePlaylist; tracks: SourceTrack[] }> }>;
+}