spotifify 0.1.1

package/src/match/normalize.ts

@@ -0,0 +1,107 @@
+import { distance } from "fastest-levenshtein";
+import { Converter } from "opencc-js/t2cn";
+
+const toSimplified = Converter({ from: "tw", to: "cn" });
+
+/** NFKC → lowercase → traditional→simplified → drop everything but letters, digits, and combining marks. */
+export function normalizeText(s: string): string {
+  return toSimplified(s.normalize("NFKC").toLowerCase()).replace(/[^\p{L}\p{N}\p{M}]/gu, "");
+}
+
+export interface NormalizedTitle {
+  core: string;
+  versionTags: Set<string>;
+}
+
+/** Keyword → canonical version tag. Tested against a lowercased, simplified annotation segment with spaces intact. */
+const VERSION_TAGS: ReadonlyArray<readonly [RegExp, string]> = [
+  [/\blive\b|现场|演唱会/, "live"],
+  [/\bremix\b|混音/, "remix"],
+  [/\binstrumental\b|\bkaraoke\b|\boff vocal\b|伴奏|纯音乐|无人声/, "instrumental"],
+  [/\bacoustic\b|\bunplugged\b|不插电/, "acoustic"],
+  [/\bdemo\b/, "demo"],
+  [/\bcover\b|翻唱/, "cover"],
+  [/\bdj\b/, "dj"],
+  [/\bpiano\b|钢琴/, "piano"],
+  [/\bradio edit\b/, "radio"],
+  [/\bextended\b/, "extended"],
+  [/\bsped up\b|\bspeed up\b/, "spedup"],
+  [/\bslowed\b/, "slowed"],
+];
+
+const BRACKETS = /\(([^()]*)\)|\[([^[\]]*)\]|【([^【】]*)】|（([^（）]*)）/g;
+const DASH_SUFFIX = /\s+[-–—]\s+(.*)$/;
+const FEAT_SUFFIX = /\s*\b(?:feat|ft)\.?\s+.*$|\s*\bfeaturing\s+.*$/i;
+
+/**
+ * Splits a title into its base text and annotation segments (bracketed groups and the ` - ` suffix).
+ * A trailing `feat. X` is dropped from the base (artists are matched separately).
+ */
+export function splitAnnotations(title: string): { base: string; segments: string[] } {
+  const segments: string[] = [];
+  let base = title.normalize("NFKC").replace(BRACKETS, (_, a?: string, b?: string, c?: string, d?: string) => {
+    segments.push(a ?? b ?? c ?? d ?? "");
+    return " ";
+  });
+  const dash = DASH_SUFFIX.exec(base);
+  if (dash) {
+    segments.push(dash[1]!);
+    base = base.slice(0, dash.index);
+  }
+  return { base: base.replace(FEAT_SUFFIX, "").trim(), segments };
+}
+
+/** Canonical version tags named by an annotation segment such as `Live at Wembley` or `伴奏`. */
+export function versionTagsOf(segment: string): string[] {
+  const text = toSimplified(segment.toLowerCase());
+  const tags: string[] = [];
+  for (const [re, tag] of VERSION_TAGS) if (re.test(text)) tags.push(tag);
+  return tags;
+}
+
+export function normalizeTitle(s: string): NormalizedTitle {
+  const { base, segments } = splitAnnotations(s);
+  const versionTags = new Set<string>();
+  for (const seg of segments) for (const tag of versionTagsOf(seg)) versionTags.add(tag);
+  const core = normalizeText(base);
+  return { core: core || normalizeText(s), versionTags };
+}
+
+const ARTIST_SPLIT = /\s*(?:[/、;,&×]|\bfeat\.?\s|\bft\.?\s|\bfeaturing\s)\s*|\s+x\s+/i;
+
+const normalizedAliasCache = new WeakMap<Record<string, string>, Map<string, string>>();
+
+function normalizedAliases(aliases: Record<string, string>): Map<string, string> {
+  let m = normalizedAliasCache.get(aliases);
+  if (!m) {
+    m = new Map();
+    for (const [k, v] of Object.entries(aliases)) m.set(normalizeText(k), normalizeText(v));
+    normalizedAliasCache.set(aliases, m);
+  }
+  return m;
+}
+
+/** Raw credit parts (trimmed, non-empty) without normalization; used when a human-readable name is needed. */
+export function splitArtists(artists: string[]): string[] {
+  return artists.flatMap((a) => a.split(ARTIST_SPLIT)).map((p) => p.trim()).filter((p) => p !== "");
+}
+
+/** Splits joint credits, normalizes each name, applies the alias table, and dedupes. */
+export function normalizeArtists(artists: string[], aliases: Record<string, string>): string[] {
+  const table = normalizedAliases(aliases);
+  const out = new Set<string>();
+  for (const a of artists) {
+    for (const part of a.split(ARTIST_SPLIT)) {
+      const n = normalizeText(part);
+      if (!n) continue;
+      out.add(table.get(n) ?? n);
+    }
+  }
+  return [...out];
+}
+
+/** 1 - levenshtein / maxLen, in [0, 1]; two empty strings are identical. */
+export function similarity(a: string, b: string): number {
+  const maxLen = Math.max(a.length, b.length);
+  return maxLen === 0 ? 1 : 1 - distance(a, b) / maxLen;
+}

package/src/match/score.ts

@@ -0,0 +1,90 @@
+import type { Config } from "../config.ts";
+import type { SpotifyTrack } from "../spotify/types.ts";
+import { normalizeArtists, normalizeTitle, similarity, type NormalizedTitle } from "./normalize.ts";
+import type { ScoreParts } from "./types.ts";
+
+export interface ScoreInput {
+  title: string;
+  aliases: string[];
+  artists: string[];
+  album?: string;
+  durationMs?: number;
+}
+
+/** Source side of a comparison, normalized once so it can be scored against many candidates. */
+export interface PreparedSource {
+  titles: NormalizedTitle[];
+  versionTags: Set<string>;
+  artists: string[];
+  album: string | null;
+  durationMs: number | undefined;
+}
+
+const W_TITLE = 0.45;
+const W_ARTIST = 0.3;
+const W_ALBUM = 0.1;
+const W_DURATION = 0.15;
+
+export function prepareSource(src: ScoreInput, cfg: Config["matching"]): PreparedSource {
+  const main = normalizeTitle(src.title);
+  return {
+    titles: [main, ...src.aliases.map(normalizeTitle)],
+    versionTags: main.versionTags,
+    artists: normalizeArtists(src.artists, cfg.artist_aliases),
+    album: src.album ? normalizeTitle(src.album).core : null,
+    durationMs: src.durationMs,
+  };
+}
+
+function setsEqual(a: Set<string>, b: Set<string>): boolean {
+  if (a.size !== b.size) return false;
+  for (const x of a) if (!b.has(x)) return false;
+  return true;
+}
+
+function artistSimilarity(a: string[], b: string[]): number {
+  if (a.length === 0 || b.length === 0) return 0;
+  let best = 0;
+  for (const x of a) {
+    for (const y of b) {
+      if (x === y) return 1;
+      const s = similarity(x, y);
+      if (s > best) best = s;
+    }
+  }
+  return best;
+}
+
+export function scorePrepared(src: PreparedSource, cand: SpotifyTrack, cfg: Config["matching"]): { score: number; parts: ScoreParts } {
+  const candTitle = normalizeTitle(cand.name);
+  let title = 0;
+  for (const t of src.titles) {
+    const s = similarity(t.core, candTitle.core);
+    if (s > title) title = s;
+  }
+  const artist = artistSimilarity(
+    src.artists,
+    normalizeArtists(
+      cand.artists.map((a) => a.name),
+      cfg.artist_aliases,
+    ),
+  );
+  const album = src.album === null ? 0.5 : similarity(src.album, normalizeTitle(cand.album.name).core);
+  let duration = 0.5;
+  if (src.durationMs !== undefined) {
+    const delta = Math.abs(src.durationMs - cand.duration_ms);
+    duration = delta <= cfg.duration_tolerance_ms ? 1 : delta <= 10_000 ? 0.5 : 0;
+  }
+  const parts: ScoreParts = { title, artist, album, duration, versionTagsAgree: setsEqual(src.versionTags, candTitle.versionTags) };
+  return { score: W_TITLE * title + W_ARTIST * artist + W_ALBUM * album + W_DURATION * duration, parts };
+}
+
+/** DESIGN.md §5.3: weighted sum of title / artist / album / duration similarities. */
+export function scoreCandidate(src: ScoreInput, cand: SpotifyTrack, cfg: Config["matching"]): { score: number; parts: ScoreParts } {
+  return scorePrepared(prepareSource(src, cfg), cand, cfg);
+}
+
+/** Hard gate for `matched(auto)`: high overall score plus strong title/artist, exact-enough duration, and agreeing version tags. */
+export function passesAutoGate(score: number, parts: ScoreParts, cfg: Config["matching"]): boolean {
+  return score >= cfg.auto_threshold && parts.title >= 0.9 && parts.artist >= 0.8 && parts.duration === 1 && parts.versionTagsAgree;
+}

package/src/match/search.ts

@@ -0,0 +1,97 @@
+import type { Config } from "../config.ts";
+import type { SpotifyApi } from "../spotify/api.ts";
+import type { SpotifyTrack } from "../spotify/types.ts";
+import type { Repo } from "../state/repo.ts";
+import { sleep } from "../util/retry.ts";
+import { splitAnnotations, versionTagsOf } from "./normalize.ts";
+import type { ScoreInput } from "./score.ts";
+
+const DAY_MS = 86_400_000;
+const SEARCH_LIMIT = 10;
+const QUOTES = /["'“”‘’]/g;
+
+/** Thrown on a cache miss once `matching.max_searches_per_run` network searches have been spent. */
+export class SearchBudgetExhaustedError extends Error {
+  constructor(readonly budget: number) {
+    super(`search budget of ${budget} requests for this run is used up`);
+    this.name = "SearchBudgetExhaustedError";
+  }
+}
+
+/** Query-friendly form of a title: annotations removed, version tags kept as plain words, quotes stripped. */
+export function queryTitle(title: string): string {
+  const { base, segments } = splitAnnotations(title);
+  const words = [base];
+  for (const seg of segments) words.push(...versionTagsOf(seg));
+  return words.join(" ").replace(QUOTES, "").replace(/\s+/g, " ").trim();
+}
+
+export class TrackSearch {
+  private readonly ttlMs: number;
+  private readonly budget: number;
+  private readonly maxQueries: number;
+  private readonly minIntervalMs: number;
+  private networkSearches = 0;
+  /** Serializes the pacing gap so concurrent callers never exceed one request per `minIntervalMs`. */
+  private gate: Promise<void> = Promise.resolve();
+
+  constructor(
+    private readonly api: SpotifyApi,
+    private readonly repo: Repo,
+    cfg: Config["matching"],
+    private readonly market: string,
+  ) {
+    this.ttlMs = cfg.search_cache_ttl_days * DAY_MS;
+    this.budget = cfg.max_searches_per_run === 0 ? Number.POSITIVE_INFINITY : cfg.max_searches_per_run;
+    this.maxQueries = cfg.max_queries_per_track;
+    this.minIntervalMs = cfg.search_min_interval_ms;
+  }
+
+  /** Network searches performed so far in this process. */
+  get used(): number {
+    return this.networkSearches;
+  }
+
+  /** Runs a search, serving from `search_cache` when a fresh entry exists for (query, market). */
+  async search(q: string, now: number): Promise<SpotifyTrack[]> {
+    const key = new Bun.CryptoHasher("sha1").update(`${q}\u0000${this.market}`).digest("hex");
+    const cached = this.repo.cacheGet<SpotifyTrack[]>(key, now, this.ttlMs);
+    if (cached) return cached;
+    if (this.networkSearches >= this.budget) throw new SearchBudgetExhaustedError(this.budget);
+    this.networkSearches++;
+    await this.pace();
+    const tracks = await this.api.searchTracks(q, this.market, SEARCH_LIMIT);
+    this.repo.cacheSet(key, tracks, now);
+    return tracks;
+  }
+
+  private pace(): Promise<void> {
+    const turn = this.gate.then(() => sleep(this.minIntervalMs));
+    this.gate = turn.catch(() => undefined);
+    return turn;
+  }
+
+  /**
+   * DESIGN.md §5.1 query sequence: isrc → fielded title+artist → free text → aliases → bare title.
+   * Deduped, in order, capped at `max_queries_per_track` while always keeping the bare-title fallback last.
+   */
+  queriesFor(src: ScoreInput & { isrc?: string }): string[] {
+    const primary = new Set<string>();
+    if (src.isrc) primary.add(`isrc:${src.isrc.toUpperCase()}`);
+    const artist = src.artists[0]?.replace(QUOTES, "").trim();
+    const titles = [src.title, ...src.aliases].map(queryTitle).filter((t) => t.length > 0);
+    for (const title of titles) {
+      if (artist) {
+        primary.add(`track:"${title}" artist:"${artist}"`);
+        primary.add(`${title} ${artist}`);
+      } else {
+        primary.add(`track:"${title}"`);
+      }
+    }
+    const bare = titles[0];
+    if (bare === undefined) return [...primary].slice(0, this.maxQueries);
+    primary.delete(bare);
+    const head = [...primary].slice(0, Math.max(0, this.maxQueries - 1));
+    return [...head, bare];
+  }
+}

package/src/match/types.ts

@@ -0,0 +1,45 @@
+export type MatchStatus = "pending" | "matched" | "review" | "local" | "skipped";
+
+export type DecidedBy = "auto" | "isrc" | "fingerprint" | "user";
+
+/** Per-component similarity in [0, 1]; see DESIGN.md §5.3 */
+export interface ScoreParts {
+  title: number;
+  artist: number;
+  album: number;
+  duration: number;
+  versionTagsAgree: boolean;
+}
+
+export interface Candidate {
+  id: string;
+  uri: string;
+  title: string;
+  artists: string[];
+  album: string;
+  durationMs: number;
+  isPlayable: boolean;
+  score: number;
+  parts: ScoreParts;
+}
+
+export interface MatchRow {
+  canonicalKey: string;
+  status: MatchStatus;
+  spotifyId: string | null;
+  spotifyUri: string | null;
+  score: number | null;
+  decidedBy: DecidedBy | null;
+  candidates: Candidate[];
+  decidedAt: number | null;
+  lastSearchAt: number | null;
+  searchCount: number;
+}
+
+/** A user decision from the review TUI or `rematch`. */
+export type Decision =
+  | { kind: "pick"; candidate: Candidate }
+  | { kind: "uri"; spotifyUri: string }
+  | { kind: "local" }
+  | { kind: "skip" }
+  | { kind: "reset" };

package/src/sources/local/ncm.ts

@@ -0,0 +1,198 @@
+import { createDecipheriv } from "node:crypto";
+import { mkdir, open, type FileHandle } from "node:fs/promises";
+import { dirname } from "node:path";
+import { z } from "zod";
+
+/**
+ * Netease `.ncm` container (layout as implemented by ncmdump):
+ *
+ *   "CTENFDAM" | 2 reserved | u32le keyLen | key (XOR 0x64, AES-128-ECB[CORE_KEY], "neteasecloudmusic" + rc4Key)
+ *   u32le metaLen | meta (XOR 0x63, "163 key(Don't modify):" + base64(AES-128-ECB[META_KEY]("music:" + json)))
+ *   u32le crc32 | 5 reserved | u32le imageSize | image | audio (XOR stream derived from RC4 S-box of rc4Key)
+ */
+
+const MAGIC = "CTENFDAM";
+const CORE_KEY = Buffer.from("687A4852416D736F356B496E62617857", "hex");
+const META_KEY = Buffer.from("2331346C6A6B5F215C5D2630553C2728", "hex");
+const KEY_PREFIX = "neteasecloudmusic".length;
+const META_PREFIX = "163 key(Don't modify):".length;
+/** Upper bound for any length-prefixed header field; real files stay far below this. */
+const MAX_FIELD = 16 << 20;
+const CHUNK = 1 << 20;
+
+export interface NcmMeta {
+  musicId: number;
+  musicName: string;
+  artist: Array<[string, number]>;
+  album: string;
+  albumId?: number;
+  alias?: string[];
+  transNames?: string[];
+  format: string;
+  /** milliseconds */
+  duration: number;
+  albumPic?: string;
+}
+
+const MetaSchema = z.object({
+  musicId: z.coerce.number(),
+  musicName: z.string(),
+  artist: z.array(z.tuple([z.string(), z.coerce.number()])).default([]),
+  album: z.string().default(""),
+  albumId: z.coerce.number().optional(),
+  alias: z.array(z.string()).optional(),
+  transNames: z.array(z.string()).optional(),
+  format: z.string(),
+  duration: z.number(),
+  albumPic: z.string().optional(),
+});
+/** "dj:" payloads (radio programs) nest the song under mainMusic. */
+const DjMetaSchema = z.object({ mainMusic: MetaSchema }).transform((o) => o.mainMusic);
+
+/** Standard RC4 key scheduling; the resulting S-box drives the audio XOR stream. Exported for tests. */
+export function keyBox(key: Uint8Array): Uint8Array {
+  const box = new Uint8Array(256);
+  for (let i = 0; i < 256; i++) box[i] = i;
+  let j = 0;
+  for (let i = 0; i < 256; i++) {
+    const s = box[i]!;
+    j = (j + s + key[i % key.length]!) & 0xff;
+    box[i] = box[j]!;
+    box[j] = s;
+  }
+  return box;
+}
+
+/** 256-byte XOR stream: audio byte at offset k is XORed with `stream[k & 0xff]`. */
+function xorStream(box: Uint8Array): Uint8Array {
+  const stream = new Uint8Array(256);
+  for (let k = 0; k < 256; k++) {
+    const j = (k + 1) & 0xff;
+    const bj = box[j]!;
+    stream[k] = box[(bj + box[(bj + j) & 0xff]!) & 0xff]!;
+  }
+  return stream;
+}
+
+function aesEcbDecrypt(key: Buffer, data: Uint8Array): Buffer {
+  const d = createDecipheriv("aes-128-ecb", key, null);
+  return Buffer.concat([d.update(data), d.final()]);
+}
+
+class Cursor {
+  pos = 0;
+
+  constructor(
+    private readonly fh: FileHandle,
+    private readonly path: string,
+  ) {}
+
+  async bytes(n: number): Promise<Buffer> {
+    if (n > MAX_FIELD) throw new Error(`${this.path}: implausible NCM field length ${n}`);
+    const buf = Buffer.allocUnsafe(n);
+    for (let done = 0; done < n; ) {
+      const { bytesRead } = await this.fh.read(buf, done, n - done, this.pos + done);
+      if (bytesRead === 0) throw new Error(`${this.path}: truncated NCM header (EOF at byte ${this.pos + done})`);
+      done += bytesRead;
+    }
+    this.pos += n;
+    return buf;
+  }
+}
+
+function parseMeta(text: string, path: string): NcmMeta {
+  const colon = text.indexOf(":");
+  if (colon < 0) throw new Error(`${path}: malformed NCM metadata (no type prefix)`);
+  const parsed = (text.startsWith("dj:") ? DjMetaSchema : MetaSchema).safeParse(JSON.parse(text.slice(colon + 1)));
+  if (!parsed.success) throw new Error(`${path}: unexpected NCM metadata shape: ${parsed.error.message}`);
+  return parsed.data;
+}
+
+const KEY_163 = "163 key(Don't modify):";
+
+/**
+ * Plain mp3/flac downloaded by the NetEase client carry the same encrypted metadata as an NCM header in a
+ * comment tag (`163 key(Don't modify):<base64>`). Returns null when the text is not such a key or does not decode.
+ */
+export function decode163Key(comment: string, path: string): NcmMeta | null {
+  const text = comment.trim();
+  if (!text.startsWith(KEY_163)) return null;
+  try {
+    return parseMeta(aesEcbDecrypt(META_KEY, Buffer.from(text.slice(KEY_163.length), "base64")).toString("utf8"), path);
+  } catch {
+    return null;
+  }
+}
+
+interface Header {
+  meta: NcmMeta;
+  stream: Uint8Array;
+  cover: Buffer | null;
+  audioOffset: number;
+}
+
+async function readHeader(fh: FileHandle, path: string, withCover: boolean): Promise<Header> {
+  const r = new Cursor(fh, path);
+  const head = await r.bytes(14);
+  if (head.toString("latin1", 0, 8) !== MAGIC) throw new Error(`${path}: not an NCM file (bad magic)`);
+
+  const keyRaw = await r.bytes(head.readUInt32LE(10));
+  for (let i = 0; i < keyRaw.length; i++) keyRaw[i] = keyRaw[i]! ^ 0x64;
+  const rc4Key = aesEcbDecrypt(CORE_KEY, keyRaw).subarray(KEY_PREFIX);
+  if (rc4Key.length === 0) throw new Error(`${path}: NCM key block is empty`);
+
+  const metaLen = (await r.bytes(4)).readUInt32LE(0);
+  if (metaLen === 0) throw new Error(`${path}: NCM file carries no embedded metadata`);
+  const metaRaw = await r.bytes(metaLen);
+  for (let i = 0; i < metaRaw.length; i++) metaRaw[i] = metaRaw[i]! ^ 0x63;
+  const metaCipher = Buffer.from(metaRaw.toString("latin1", META_PREFIX), "base64");
+  const meta = parseMeta(aesEcbDecrypt(META_KEY, metaCipher).toString("utf8"), path);
+
+  r.pos += 9; // crc32 + 5 reserved bytes
+  const imageSize = (await r.bytes(4)).readUInt32LE(0);
+  let cover: Buffer | null = null;
+  if (withCover && imageSize > 0) cover = await r.bytes(imageSize);
+  else r.pos += imageSize;
+
+  return { meta, stream: xorStream(keyBox(rc4Key)), cover, audioOffset: r.pos };
+}
+
+/** Parses only the header (key + metadata); never touches the audio or cover bytes. */
+export async function readNcmMeta(path: string): Promise<NcmMeta> {
+  const fh = await open(path, "r");
+  try {
+    return (await readHeader(fh, path, false)).meta;
+  } finally {
+    await fh.close();
+  }
+}
+
+async function writeAll(fh: FileHandle, buf: Buffer, length: number): Promise<void> {
+  for (let off = 0; off < length; ) off += (await fh.write(buf, off, length - off)).bytesWritten;
+}
+
+/** Streams the decrypted audio to `outPath` (parent dir created) and returns the metadata plus embedded cover. */
+export async function decryptNcm(path: string, outPath: string): Promise<{ meta: NcmMeta; cover: Uint8Array | null }> {
+  const fh = await open(path, "r");
+  try {
+    const { meta, stream, cover, audioOffset } = await readHeader(fh, path, true);
+    await mkdir(dirname(outPath), { recursive: true });
+    const out = await open(outPath, "w");
+    try {
+      const buf = Buffer.allocUnsafe(CHUNK);
+      for (let pos = audioOffset; ; ) {
+        const { bytesRead } = await fh.read(buf, 0, CHUNK, pos);
+        if (bytesRead === 0) break;
+        const base = pos - audioOffset;
+        for (let i = 0; i < bytesRead; i++) buf[i] = buf[i]! ^ stream[(base + i) & 0xff]!;
+        await writeAll(out, buf, bytesRead);
+        pos += bytesRead;
+      }
+    } finally {
+      await out.close();
+    }
+    return { meta, cover };
+  } finally {
+    await fh.close();
+  }
+}

package/src/sources/local/scan.ts

@@ -0,0 +1,55 @@
+import type { Dirent } from "node:fs";
+import { readdir, stat } from "node:fs/promises";
+import { extname, join, resolve } from "node:path";
+import { log } from "../../util/log.ts";
+
+export interface ScannedFile {
+  path: string;
+  size: number;
+  /** integer milliseconds (sub-ms precision dropped so cached values compare exactly) */
+  mtimeMs: number;
+}
+
+/**
+ * Recursively lists files under `dirs` whose extension is in `extensions` (case-insensitive, with or without the dot).
+ * Dot-entries and symlinks are skipped; a missing/unreadable root throws, an unreadable subdirectory is logged and skipped.
+ * Result paths are absolute, de-duplicated, and sorted by ordinal comparison.
+ */
+export async function scanDirs(dirs: string[], extensions: string[]): Promise<ScannedFile[]> {
+  const exts = new Set(extensions.map((e) => "." + e.replace(/^\./, "").toLowerCase()));
+  const seen = new Set<string>();
+  const out: ScannedFile[] = [];
+  for (const dir of dirs) {
+    const root = resolve(dir);
+    await walk(root, await readdir(root, { withFileTypes: true }), exts, seen, out);
+  }
+  out.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+  return out;
+}
+
+async function walk(
+  dir: string,
+  entries: Dirent[],
+  exts: Set<string>,
+  seen: Set<string>,
+  out: ScannedFile[],
+): Promise<void> {
+  for (const ent of entries) {
+    if (ent.name.startsWith(".")) continue;
+    const full = join(dir, ent.name);
+    if (ent.isDirectory()) {
+      let children;
+      try {
+        children = await readdir(full, { withFileTypes: true });
+      } catch (e) {
+        log.warn(`skipping unreadable directory ${full}: ${e instanceof Error ? e.message : String(e)}`);
+        continue;
+      }
+      await walk(full, children, exts, seen, out);
+    } else if (ent.isFile() && exts.has(extname(ent.name).toLowerCase()) && !seen.has(full)) {
+      seen.add(full);
+      const st = await stat(full);
+      out.push({ path: full, size: st.size, mtimeMs: Math.floor(st.mtimeMs) });
+    }
+  }
+}