music: index artist discographies (album → release type) for the app

Each Albums/<Artist>/_discography.md (author-maintained source of truth, never modified) is compiled into a per-artist discography.json in the cache = album folder → normalized release type (Studio/Live/Compilation/Single/EP/…), so the player can split an artist's album list into sections. - indexer.ts: parse the md table, normalize the Type (EP?→EP, Compilation (VA)→ Compilation, …), write discography.json. The artist folder's `v` now includes _discography.md so regenerating it re-syncs just that small JSON (isolated from the albums' meta/cover). Manifest gains `disco: true` on such entries. Also fixed the skip check to require all expected outputs to exist, so artist/ cover-only folders no longer rebuild every run. New `discographies` counter. - sidecar: GET /discography?path=<artist rel> (ETag/304), documented in the contract header. - MUSIC_API.md: §2.4 + manifest disco flag + resync algorithm updated. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-07-26 09:39:11 +00:00
parent 592cc72f85
commit 946da85e4c
3 changed files with 134 additions and 23 deletions
@@ -10,6 +10,7 @@ import {
  albumVersion,
  metaFilePath,
  coverFilePath,
+  discographyFilePath,
  onIndexProgress,
  buildReport,
 } from './indexer';
@@ -30,9 +31,14 @@ const DATA_PATH = process.env.DATA_PATH ?? join(process.cwd(), 'data');
 //
 //   GET  /stream?path=<home-relative>      audio with Range→206 (Content-Range/Length/Accept-Ranges)
 //                                          + `X-Audio-Duration` (seconds, ffprobe). 400/404/416.
-//   GET  /manifest                         { version, generatedAt, albums: { "<rel>": { v, cover, tracks } } }
+//   GET  /manifest                         { version, generatedAt, albums: { "<rel>": { v, cover, tracks, disco? } } }
 //   GET  /meta?path=<rel>                  album meta.json (IndexMeta). ETag: <v>; If-None-Match → 304.
 //   GET  /cover?path=<rel>                 compressed cover.jpg.       ETag: <v>; If-None-Match → 304.
+//   GET  /discography?path=<artist rel>    artist discography.json (only where manifest entry has
+//                                          disco:true) = { artist, albums: { "<[year] album folder>":
+//                                          "<Type>" } }, Type ∈ Studio/Live/Compilation/Single/EP/…
+//                                          ETag: <v>; If-None-Match → 304. Source: each artist folder's
+//                                          _discography.md (normalized; the md itself is never modified).
 //   POST /reindex                          start an async build; returns IndexStatus (running: true).
 //   GET  /reindex/status                   IndexStatus snapshot.
 //   GET  /reindex/stream                   SSE. Triggers a build if idle (`?trigger=0` = watch-only).
@@ -135,21 +141,21 @@ const server = Bun.serve({
    // ── Sync surface ──
    if (url.pathname === '/manifest') return json(await getManifest());

-    if (url.pathname === '/meta' || url.pathname === '/cover') {
+    if (url.pathname === '/meta' || url.pathname === '/cover' || url.pathname === '/discography') {
      const rel = url.searchParams.get('path');
      if (rel === null) return new Response('path is required', { status: 400 });
-      const isMeta = url.pathname === '/meta';
-      const file = isMeta ? metaFilePath(rel) : coverFilePath(rel);
-      if (!file) return new Response('Invalid path', { status: 400 });
-      if (!(await Bun.file(file).exists())) return new Response('Not found', { status: 404 });
+      const spec = {
+        '/meta': { file: metaFilePath(rel), type: 'application/json' },
+        '/cover': { file: coverFilePath(rel), type: 'image/jpeg' },
+        '/discography': { file: discographyFilePath(rel), type: 'application/json' },
+      }[url.pathname]!;
+      if (!spec.file) return new Response('Invalid path', { status: 400 });
+      if (!(await Bun.file(spec.file).exists())) return new Response('Not found', { status: 404 });

      const v = await albumVersion(rel);
      if (v && req.headers.get('if-none-match') === v) return new Response(null, { status: 304 });
-      return new Response(Bun.file(file), {
-        headers: {
-          'Content-Type': isMeta ? 'application/json' : 'image/jpeg',
-          ...(v ? { ETag: v } : {}),
-        },
+      return new Response(Bun.file(spec.file), {
+        headers: { 'Content-Type': spec.type, ...(v ? { ETag: v } : {}) },
      });
    }

@@ -1,6 +1,6 @@
 import { readdir, stat, mkdir, writeFile, readFile, rm } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
-import { join, relative } from 'node:path';
+import { join, relative, basename } from 'node:path';
 import { homedir } from 'node:os';

 // Server-side music library indexer — the platform counterpart of the app's music-index.ts. Walks the
@@ -23,6 +23,7 @@ const MANIFEST_PATH = join(CACHE_ROOT, 'manifest.json');

 const AUDIO_EXT = new Set(['mp3', 'flac', 'm4a', 'aac', 'ogg', 'opus', 'wav', 'wma', 'mp4']);
 const COVER_FILES = ['folder.jpg', 'cover.jpg', 'folder.png', 'cover.png'];
+const DISCO_FILE = '_discography.md';
 const TRACK_CONCURRENCY = 6;
 const COVER_MAX_PX = 600;

@@ -40,9 +41,45 @@ export type IndexTrack = {
 };
 export type IndexMeta = { path: string; cover?: string; tracks: IndexTrack[] };

-type ManifestEntry = { v: string; cover: boolean; tracks: number };
+type ManifestEntry = { v: string; cover: boolean; tracks: number; disco?: boolean };
 type Manifest = { version: number; generatedAt: number; albums: Record<string, ManifestEntry> };

+// ── Discography (artist-level _discography.md → album folder → normalized type) ──
+
+/** Canonical section for a Type cell. The source _discography.md is NEVER modified — this only cleans
+ *  the derived JSON so the phone groups into tidy sections. Unknown types pass through trimmed. */
+function normalizeType(raw: string): string {
+  const t = raw.trim().replace(/\?+$/, '').trim(); // "EP?" → "EP", "Single?" → "Single"
+  const lower = t.toLowerCase();
+  if (lower.startsWith('compilation')) return 'Compilation'; // "Compilation (VA)" → "Compilation"
+  const map: Record<string, string> = {
+    studio: 'Studio',
+    live: 'Live',
+    single: 'Single',
+    ep: 'EP',
+    soundtrack: 'Soundtrack',
+    remix: 'Remix',
+    'dj-mix': 'DJ-Mix',
+    djmix: 'DJ-Mix',
+    demo: 'Demo',
+    mixtape: 'Mixtape',
+    bootleg: 'Bootleg',
+    other: 'Other',
+  };
+  return map[lower] ?? t;
+}
+
+/** Parse the md table into { "[year] album" (folder name) → normalized type }. */
+function parseDiscography(mdText: string): Record<string, string> {
+  const albums: Record<string, string> = {};
+  for (const line of mdText.split('\n')) {
+    const m = line.match(/^\|\s*(\d{4})\s*\|\s*(.+?)\s*\|\s*([^|]+?)\s*\|/);
+    if (!m) continue; // header/separator/non-rows don't match (Year isn't 4 digits)
+    albums[`[${m[1]}] ${m[2]}`] = normalizeType(m[3]!);
+  }
+  return albums;
+}
+
 export type IndexStatus = {
  running: boolean;
  startedAt: number | null;
@@ -52,6 +89,7 @@ export type IndexStatus = {
  albumsSkipped: number; // unchanged (v matched)
  tracksIndexed: number;
  coversSaved: number;
+  discographies: number; // artist discography.json files written
  currentPath: string;
  error: string | null;
 };
@@ -93,6 +131,7 @@ const status: IndexStatus = {
  albumsSkipped: 0,
  tracksIndexed: 0,
  coversSaved: 0,
+  discographies: 0,
  currentPath: '',
  error: null,
 };
@@ -108,6 +147,7 @@ export type IndexReport = {
  foldersScanned: number;
  tracksIndexed: number;
  coversSaved: number;
+  discographies: number;
  elapsedSec: number;
  error: string | null;
 };
@@ -121,6 +161,7 @@ export function buildReport(s: IndexStatus = status): IndexReport {
    foldersScanned: s.foldersScanned,
    tracksIndexed: s.tracksIndexed,
    coversSaved: s.coversSaved,
+    discographies: s.discographies,
    elapsedSec: Math.round(elapsed * 10) / 10,
    error: s.error,
  };
@@ -250,6 +291,7 @@ export async function buildMusicIndex(): Promise<IndexStatus> {
    albumsSkipped: 0,
    tracksIndexed: 0,
    coversSaved: 0,
+    discographies: 0,
    currentPath: '',
    error: null,
  });
@@ -300,8 +342,11 @@ async function walk(dirAbs: string, prev: Manifest, next: Manifest): Promise<voi
  const coverName = COVER_FILES.find((c) => files.some((e) => e.name === c));
  const rel = relative(MUSIC_ROOT, dirAbs); // '' at root

-  if (audio.length || coverName) {
-    // Source signature → version.
+  const hasDisco = files.some((e) => e.name === DISCO_FILE);
+
+  if (audio.length || coverName || hasDisco) {
+    // Source signature → version (includes _discography.md so regenerating it bumps v — isolated from
+    // the album meta/cover of the tracks underneath).
    const sigParts: string[] = [];
    for (const name of [...audio].sort()) {
      const st = await stat(join(dirAbs, name)).catch(() => null);
@@ -311,11 +356,23 @@ async function walk(dirAbs: string, prev: Manifest, next: Manifest): Promise<voi
      const st = await stat(join(dirAbs, coverName)).catch(() => null);
      if (st) sigParts.push(`cover:${coverName}:${st.size}:${Math.round(st.mtimeMs)}`);
    }
+    if (hasDisco) {
+      const st = await stat(join(dirAbs, DISCO_FILE)).catch(() => null);
+      if (st) sigParts.push(`disco:${st.size}:${Math.round(st.mtimeMs)}`);
+    }
    const v = Bun.hash(sigParts.join('|')).toString(16);
    const cacheDir = join(CACHE_ROOT, rel);
-    const metaExists = existsSync(join(cacheDir, 'meta.json'));

-    if (prev.albums[rel]?.v === v && metaExists) {
+    // Skip only if v matches AND every expected output already exists (fixes cover-only/artist folders
+    // that have no meta.json from rebuilding every run).
+    const expected = [
+      audio.length ? 'meta.json' : null,
+      coverName ? 'cover.jpg' : null,
+      hasDisco ? 'discography.json' : null,
+    ].filter((f): f is string => f !== null);
+    const outputsExist = expected.every((f) => existsSync(join(cacheDir, f)));
+
+    if (prev.albums[rel]?.v === v && outputsExist) {
      status.albumsSkipped += 1;
    } else {
      await mkdir(cacheDir, { recursive: true });
@@ -335,10 +392,22 @@ async function walk(dirAbs: string, prev: Manifest, next: Manifest): Promise<voi
        const meta: IndexMeta = { path: rel, cover: coverName ? 'cover.jpg' : undefined, tracks };
        await writeFile(join(cacheDir, 'meta.json'), JSON.stringify(meta));
      }
+
+      if (hasDisco) {
+        try {
+          const md = await readFile(join(dirAbs, DISCO_FILE), 'utf8');
+          const disco = { artist: basename(dirAbs), albums: parseDiscography(md) };
+          await writeFile(join(cacheDir, 'discography.json'), JSON.stringify(disco));
+          status.discographies += 1;
+        } catch {
+          /* skip discography on failure */
+        }
+      }
+
      status.albumsBuilt += 1;
    }

-    next.albums[rel] = { v, cover: !!coverName, tracks: audio.length };
+    next.albums[rel] = { v, cover: !!coverName, tracks: audio.length, ...(hasDisco ? { disco: true } : {}) };
  }

  for (const d of subdirs) await walk(join(dirAbs, d.name), prev, next);
@@ -359,3 +428,6 @@ export function metaFilePath(rel: string): string | null {
 export function coverFilePath(rel: string): string | null {
  return resolveCachePath(rel, 'cover.jpg');
 }
+export function discographyFilePath(rel: string): string | null {
+  return resolveCachePath(rel, 'discography.json');
+}