komado 0.1.0

package/src/sources/local/index.js

@@ -0,0 +1,155 @@
+import fs from 'node:fs';
+import fsp from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { makeManga, makeChapter, globalKey } from '../../domain/shape.js';
+import { envelope, paginate } from '../../lib/envelope.js';
+import { naturalSort, naturalCompare } from '../../lib/natsort.js';
+import { NotFoundError } from '../../lib/AppError.js';
+import { getConfig } from '../../state/store.js';
+import { listArchiveImages, readArchiveEntry, isArchive } from './archive.js';
+
+export const id = 'local';
+export const label = 'Local library';
+export const remote = false;
+
+const IMAGE_RE = /\.(jpe?g|png|gif|webp|bmp|avif)$/i;
+
+// Built model: mangaId(=path) -> { mangaId, title, chapters: [{ kind, dir|file, name }] }
+let model = null;
+
+function listDir(dir) {
+  try { return fs.readdirSync(dir, { withFileTypes: true }); }
+  catch { return []; }
+}
+const hasImages = (dir) => listDir(dir).some((d) => d.isFile() && IMAGE_RE.test(d.name));
+const cleanName = (name) => name.replace(/\.(cbz|zip|cbr|rar)$/i, '');
+const expandHome = (p) => (p.startsWith('~') ? path.join(os.homedir(), p.slice(1)) : p);
+
+// A directory is a manga. Its chapters are: image subfolders, then archive
+// files; or — if neither — the loose images in the folder become one chapter.
+function buildMangaFromDir(dirPath) {
+  const entries = listDir(dirPath);
+  const chapters = [];
+
+  const chapterDirs = entries.filter((e) => e.isDirectory() && hasImages(path.join(dirPath, e.name)));
+  for (const d of naturalSort(chapterDirs, (e) => e.name)) {
+    chapters.push({ kind: 'dir', dir: path.join(dirPath, d.name), name: d.name });
+  }
+  const archives = entries.filter((e) => e.isFile() && isArchive(e.name));
+  for (const f of naturalSort(archives, (e) => e.name)) {
+    chapters.push({ kind: 'archive', file: path.join(dirPath, f.name), name: f.name });
+  }
+  if (chapters.length === 0 && hasImages(dirPath)) {
+    chapters.push({ kind: 'dir', dir: dirPath, name: path.basename(dirPath) });
+  }
+  return chapters.length ? { mangaId: dirPath, title: path.basename(dirPath), chapters } : null;
+}
+
+// A standalone .cbz/.zip is a single-chapter manga.
+function buildMangaFromArchive(filePath) {
+  return {
+    mangaId: filePath,
+    title: cleanName(path.basename(filePath)),
+    chapters: [{ kind: 'archive', file: filePath, name: path.basename(filePath) }],
+  };
+}
+
+export function scan() {
+  model = new Map();
+  for (const libPath of getConfig().localLibraryPaths || []) {
+    const abs = path.resolve(expandHome(libPath));
+    for (const entry of naturalSort(listDir(abs), (e) => e.name)) {
+      const full = path.join(abs, entry.name);
+      const built = entry.isDirectory()
+        ? buildMangaFromDir(full)
+        : isArchive(entry.name) ? buildMangaFromArchive(full) : null;
+      if (built) model.set(built.mangaId, built);
+    }
+  }
+  return model;
+}
+
+function ensureModel() {
+  if (!model) scan();
+  return model;
+}
+
+function toManga(built) {
+  return makeManga({
+    source: id,
+    id: built.mangaId,
+    title: built.title,
+    status: 'local',
+    chaptersCount: built.chapters.length,
+    language: getConfig().language,
+    raw: { path: built.mangaId },
+  });
+}
+
+export async function search(query, { offset = 0, limit = 1000 } = {}) {
+  ensureModel();
+  const q = (query || '').toLowerCase();
+  let list = [...model.values()];
+  if (q) list = list.filter((b) => b.title.toLowerCase().includes(q));
+  list.sort((a, b) => naturalCompare(a.title, b.title));
+  const data = list.slice(offset, offset + limit).map(toManga);
+  return envelope(data, {
+    pagination: paginate({ offset, limit, total: list.length }),
+    meta: { source: id, query },
+  });
+}
+
+export async function getManga(mangaId) {
+  ensureModel();
+  const built = model.get(mangaId);
+  if (!built) throw new NotFoundError(`Local manga not found: ${mangaId}`);
+  return toManga(built);
+}
+
+export async function listChapters(mangaId, { offset = 0, limit = 100_000 } = {}) {
+  ensureModel();
+  const built = model.get(mangaId);
+  if (!built) throw new NotFoundError(`Local manga not found: ${mangaId}`);
+  const mangaKey = globalKey(id, mangaId);
+  const data = built.chapters.map((ch, i) =>
+    makeChapter({
+      source: id,
+      id: `${mangaId}#${i}`,
+      mangaKey,
+      number: built.chapters.length > 1 ? String(i + 1) : null,
+      title: cleanName(ch.name),
+      raw: ch,
+    }),
+  );
+  return envelope(data.slice(offset, offset + limit), {
+    pagination: paginate({ offset, limit, total: data.length }),
+    meta: { source: id, mangaId },
+  });
+}
+
+export async function getPages(chapterId) {
+  ensureModel();
+  const hash = chapterId.lastIndexOf('#');
+  const mangaId = chapterId.slice(0, hash);
+  const chIndex = Number(chapterId.slice(hash + 1));
+  const built = model.get(mangaId);
+  if (!built) throw new NotFoundError(`Local manga not found: ${mangaId}`);
+  const ch = built.chapters[chIndex];
+  if (!ch) throw new NotFoundError(`Chapter not found: ${chapterId}`);
+
+  if (ch.kind === 'dir') {
+    const files = naturalSort(
+      listDir(ch.dir).filter((e) => e.isFile() && IMAGE_RE.test(e.name)).map((e) => e.name),
+    );
+    return files.map((name, index) => ({ index, kind: 'file', file: path.join(ch.dir, name) }));
+  }
+  const names = await listArchiveImages(ch.file);
+  return names.map((entry, index) => ({ index, kind: 'archive', file: ch.file, entry }));
+}
+
+export async function loadPageBuffer(page) {
+  if (page.kind === 'file') return fsp.readFile(page.file);
+  if (page.kind === 'archive') return readArchiveEntry(page.file, page.entry);
+  throw new NotFoundError('Unknown local page descriptor');
+}

package/src/sources/mangadex/auth.js

@@ -0,0 +1,125 @@
+import { fetchWithBackoff } from '../../lib/fetchWithBackoff.js';
+import { MANGADEX } from '../../config.js';
+import { AuthError } from '../../lib/AppError.js';
+import { getCredentials, setCredentials, clearCredentials } from '../../state/store.js';
+import { logger } from '../../lib/logger.js';
+
+// MangaDex auth is OAuth2 "personal clients" (Keycloak). The user registers a
+// client at mangadex.org/settings, then we exchange client id/secret + their
+// username/password for a short-lived (15-min) access token and a rotating
+// refresh token. Reading manga needs none of this — login only unlocks the
+// user's follows/library and read-marker sync.
+
+// The access token lives in memory only; the refresh token is the durable
+// secret (persisted by the credential store).
+let access = { token: null, expiresAt: 0 };
+let refreshing = null; // shared in-flight refresh promise (stampede guard)
+
+const FORM = { 'Content-Type': 'application/x-www-form-urlencoded' };
+const SKEW_MS = 30_000; // refresh this far ahead of the real expiry
+
+export function isLoggedIn() {
+  return !!getCredentials();
+}
+
+function postToken(params, signal) {
+  return fetchWithBackoff(MANGADEX.auth, {
+    method: 'POST',
+    headers: FORM,
+    body: new URLSearchParams(params).toString(),
+    signal,
+    retries: 1,
+  });
+}
+
+async function tokenRequest(params, { signal } = {}) {
+  // Ask for an OFFLINE refresh token so the session survives app restarts and
+  // long idle gaps (it's refreshed on each use, ~30-day idle window) instead of
+  // dying with the short-lived SSO session. If the client isn't allowed that
+  // scope, transparently fall back to a normal token so login still works.
+  let res = await postToken({ ...params, scope: 'offline_access' }, signal);
+  if (res.status === 400) {
+    const probe = await res.clone().json().catch(() => ({}));
+    if (probe.error === 'invalid_scope') res = await postToken(params, signal);
+  }
+  const json = await res.json().catch(() => ({}));
+  if (!res.ok) {
+    const detail = json.error_description || json.error || `HTTP ${res.status}`;
+    throw new AuthError(authMessage(res.status, detail), {
+      meta: { statusCode: res.status, oauthError: json.error },
+    });
+  }
+  return json;
+}
+
+function applyTokens(creds, json) {
+  access = {
+    token: json.access_token,
+    expiresAt: Date.now() + (Number(json.expires_in) || 900) * 1000,
+  };
+  // The refresh token rotates on each use — persist the latest one.
+  setCredentials({ ...creds, refreshToken: json.refresh_token || creds.refreshToken });
+}
+
+export async function login({ clientId, clientSecret, username, password }, { signal } = {}) {
+  const json = await tokenRequest({
+    grant_type: 'password',
+    username,
+    password,
+    client_id: clientId,
+    client_secret: clientSecret,
+  }, { signal });
+  applyTokens({ clientId, clientSecret, refreshToken: json.refresh_token }, json);
+  return true;
+}
+
+export function logout() {
+  access = { token: null, expiresAt: 0 };
+  refreshing = null;
+  clearCredentials();
+}
+
+// Returns a currently-valid access token, refreshing if needed, or null when
+// not logged in. `force` ignores the cached token (used after a 401).
+export async function getAccessToken({ signal, force = false } = {}) {
+  const creds = getCredentials();
+  if (!creds) return null;
+  if (!force && access.token && Date.now() < access.expiresAt - SKEW_MS) {
+    return access.token;
+  }
+  if (!refreshing) {
+    refreshing = (async () => {
+      try {
+        const json = await tokenRequest({
+          grant_type: 'refresh_token',
+          refresh_token: creds.refreshToken,
+          client_id: creds.clientId,
+          client_secret: creds.clientSecret,
+        }, { signal });
+        applyTokens(creds, json);
+        return access.token;
+      } catch (err) {
+        // Only drop the saved session when the refresh token is DEFINITIVELY
+        // dead (expired/revoked → invalid_grant). Transient or unexpected
+        // failures keep the credentials so the next call — or next launch — can
+        // recover, instead of silently logging the user out.
+        if (err.oauthError === 'invalid_grant') {
+          logger.warn('MangaDex refresh token expired/revoked — logging out', err);
+          logout();
+        }
+        throw err;
+      } finally {
+        refreshing = null;
+      }
+    })();
+  }
+  return refreshing;
+}
+
+function authMessage(status, detail) {
+  if (status === 401) return 'Login failed: check your username, password, and client credentials.';
+  if (status === 400 && /client/i.test(detail)) {
+    return 'Login failed: client not approved yet, or wrong client id / secret.';
+  }
+  return `Login failed (${status}): ${detail}`;
+}

package/src/sources/mangadex/client.js

@@ -0,0 +1,83 @@
+import { fetchJson, fetchWithBackoff } from '../../lib/fetchWithBackoff.js';
+import { MANGADEX } from '../../config.js';
+import { AuthError, SourceError } from '../../lib/AppError.js';
+import { getAccessToken, isLoggedIn } from './auth.js';
+
+const headers = {
+  'User-Agent': MANGADEX.userAgent,
+  Accept: 'application/json',
+};
+
+// MangaDex uses PHP-style array/object query params:
+//   includes[]=cover_art   contentRating[]=safe   order[chapter]=asc
+function qs(params) {
+  const sp = new URLSearchParams();
+  for (const [key, value] of Object.entries(params)) {
+    if (value == null) continue;
+    if (Array.isArray(value)) {
+      value.forEach((item) => sp.append(`${key}[]`, item));
+    } else if (typeof value === 'object') {
+      for (const [ik, iv] of Object.entries(value)) sp.append(`${key}[${ik}]`, iv);
+    } else {
+      sp.append(key, value);
+    }
+  }
+  return sp.toString();
+}
+
+// Resolve the Authorization header. `auth:true` endpoints REQUIRE a token (and
+// error clearly without one); public endpoints attach it best-effort when the
+// user is logged in, but never block browsing if the session can't refresh.
+async function authHeader({ auth, signal }) {
+  if (auth) {
+    const token = await getAccessToken({ signal });
+    if (!token) throw new AuthError('Log in to MangaDex to use this feature.');
+    return { Authorization: `Bearer ${token}` };
+  }
+  if (isLoggedIn()) {
+    const token = await getAccessToken({ signal }).catch(() => null);
+    if (token) return { Authorization: `Bearer ${token}` };
+  }
+  return {};
+}
+
+export async function mdGet(path, params, { signal, auth = false } = {}) {
+  const url = `${MANGADEX.api}${path}${params ? `?${qs(params)}` : ''}`;
+  const h = { ...headers, ...(await authHeader({ auth, signal })) };
+  try {
+    return await fetchJson(url, { headers: h, signal });
+  } catch (err) {
+    // Token revoked server-side mid-session: force a refresh and retry once.
+    if (auth && err.statusCode === 401 && isLoggedIn()) {
+      const token = await getAccessToken({ signal, force: true });
+      return fetchJson(url, { headers: { ...h, Authorization: `Bearer ${token}` }, signal });
+    }
+    throw err;
+  }
+}
+
+export async function mdSend(method, path, body, { signal, auth = true } = {}) {
+  const url = `${MANGADEX.api}${path}`;
+  const send = async (h) => {
+    const res = await fetchWithBackoff(url, {
+      method,
+      headers: h,
+      body: body == null ? undefined : JSON.stringify(body),
+      signal,
+    });
+    if (!res.ok) {
+      throw new SourceError(`HTTP ${res.status} for ${url}`, { meta: { statusCode: res.status } });
+    }
+    return res.json().catch(() => ({}));
+  };
+  const base = { ...headers, 'Content-Type': 'application/json', ...(await authHeader({ auth, signal })) };
+  try {
+    return await send(base);
+  } catch (err) {
+    if (auth && err.statusCode === 401 && isLoggedIn()) {
+      const token = await getAccessToken({ signal, force: true });
+      return send({ ...base, Authorization: `Bearer ${token}` });
+    }
+    throw err;
+  }
+}

package/src/sources/mangadex/index.js

@@ -0,0 +1,166 @@
+import { mdGet, mdSend } from './client.js';
+import { isLoggedIn } from './auth.js';
+import { normalizeManga, normalizeChapter } from './normalize.js';
+import { fetchWithBackoff } from '../../lib/fetchWithBackoff.js';
+import { createCache } from '../../lib/cache.js';
+import { envelope, paginate } from '../../lib/envelope.js';
+import { NotFoundError } from '../../lib/AppError.js';
+import { MANGADEX } from '../../config.js';
+import { globalKey } from '../../domain/shape.js';
+import { getConfig } from '../../state/store.js';
+import { logger } from '../../lib/logger.js';
+
+export const id = 'mangadex';
+export const label = 'MangaDex';
+export const remote = true;
+
+const cache = createCache({ ttlMs: 5 * 60_000, negativeTtlMs: 15_000 });
+
+export async function search(query, { offset = 0, limit = MANGADEX.pageLimit, signal } = {}) {
+  const cfg = getConfig();
+  const order = query ? { relevance: 'desc' } : { followedCount: 'desc' };
+  const key = `search:${query}:${offset}:${limit}:${cfg.contentRating.join(',')}`;
+  const res = await cache.wrap(key, () =>
+    mdGet('/manga', {
+      title: query || undefined,
+      limit,
+      offset,
+      includes: ['cover_art', 'author', 'artist'],
+      contentRating: cfg.contentRating,
+      hasAvailableChapters: 'true',
+      order,
+    }, { signal }),
+  );
+  const data = (res.data || []).map(normalizeManga);
+  return envelope(data, {
+    pagination: paginate({ offset: res.offset, limit: res.limit, total: res.total }),
+    meta: { source: id, query },
+  });
+}
+
+export async function getManga(mangaId, { signal } = {}) {
+  const res = await cache.wrap(`manga:${mangaId}`, () =>
+    mdGet(`/manga/${mangaId}`, { includes: ['cover_art', 'author', 'artist'] }, { signal }),
+  );
+  if (!res.data) throw new NotFoundError(`Manga ${mangaId} not found`);
+  return normalizeManga(res.data);
+}
+
+export async function listChapters(mangaId, { offset = 0, limit = 96, language, signal } = {}) {
+  const cfg = getConfig();
+  const lang = language || cfg.language;
+  const key = `chapters:${mangaId}:${lang}:${offset}:${limit}`;
+  const res = await cache.wrap(key, () =>
+    mdGet(`/manga/${mangaId}/feed`, {
+      limit,
+      offset,
+      translatedLanguage: lang ? [lang] : undefined,
+      contentRating: cfg.contentRating,
+      includes: ['scanlation_group'],
+      order: { volume: 'asc', chapter: 'asc' },
+    }, { signal }),
+  );
+
+  const mangaKey = globalKey(id, mangaId);
+  // MangaDex returns one row per scanlation; collapse duplicates by chapter no.
+  const seen = new Set();
+  const data = [];
+  for (const entry of res.data || []) {
+    // Externally-hosted chapters (MangaPlus etc.) have no pages we can render.
+    if (entry.attributes?.externalUrl) continue;
+    const ch = normalizeChapter(entry, mangaKey);
+    const dedup = `${ch.volume}:${ch.number}`;
+    if (ch.number != null && seen.has(dedup)) continue;
+    seen.add(dedup);
+    data.push(ch);
+  }
+  return envelope(data, {
+    pagination: paginate({ offset: res.offset, limit: res.limit, total: res.total }),
+    meta: { source: id, mangaId, language: lang },
+  });
+}
+
+// Page descriptors with a directly fetchable URL. The at-home token in baseUrl
+// expires fast, so this is only briefly cached.
+export async function getPages(chapterId, { signal } = {}) {
+  const cfg = getConfig();
+  const server = await cache.wrap(
+    `pages:${chapterId}:${cfg.dataSaver ? 'ds' : 'hq'}`,
+    () => mdGet(`/at-home/server/${chapterId}`, null, { signal }),
+    60_000,
+  );
+  if (!server.chapter) throw new NotFoundError(`No pages for chapter ${chapterId}`);
+
+  // Prefer the configured quality, but fall back to the other if it's empty.
+  let mode = cfg.dataSaver ? 'data-saver' : 'data';
+  let files = cfg.dataSaver ? server.chapter.dataSaver : server.chapter.data;
+  if (!files || files.length === 0) {
+    mode = cfg.dataSaver ? 'data' : 'data-saver';
+    files = cfg.dataSaver ? server.chapter.data : server.chapter.dataSaver;
+  }
+  if (!files || files.length === 0) {
+    throw new NotFoundError(`Chapter ${chapterId} has no hosted pages`);
+  }
+  return files.map((file, index) => ({
+    index,
+    url: `${server.baseUrl}/${mode}/${server.chapter.hash}/${file}`,
+  }));
+}
+
+export async function loadPageBuffer(page, { signal } = {}) {
+  const res = await fetchWithBackoff(page.url, {
+    headers: { 'User-Agent': MANGADEX.userAgent },
+    timeoutMs: 30_000,
+    signal,
+  });
+  if (!res.ok) throw new NotFoundError(`Failed to load page ${page.index} (${res.status})`);
+  return Buffer.from(await res.arrayBuffer());
+}
+
+// ---- Authenticated features (require login) ----------------------------
+
+// The signed-in user's followed manga, normalized like search results.
+export async function getFollows({ offset = 0, limit = MANGADEX.pageLimit, signal } = {}) {
+  // /user/follows/manga rejects contentRating[] (HTTP 400) — it returns ALL of
+  // the user's follows regardless of rating, which is what we want here anyway.
+  const res = await mdGet('/user/follows/manga', {
+    limit,
+    offset,
+    includes: ['cover_art', 'author', 'artist'],
+  }, { signal, auth: true });
+  const data = (res.data || []).map(normalizeManga);
+  return envelope(data, {
+    pagination: paginate({ offset: res.offset, limit: res.limit, total: res.total }),
+    meta: { source: id },
+  });
+}
+
+// Chapter IDs the user has marked read for this manga (for decorating the list).
+export async function getReadMarkers(mangaId, { signal } = {}) {
+  const res = await mdGet(`/manga/${mangaId}/read`, null, { signal, auth: true });
+  return res.data || [];
+}
+
+export async function markChaptersRead(mangaId, chapterIdsRead, { signal } = {}) {
+  if (!chapterIdsRead?.length) return;
+  await mdSend('POST', `/manga/${mangaId}/read`, {
+    chapterIdsRead,
+    chapterIdsUnread: [],
+  }, { signal });
+}
+
+// Fire-and-forget read-marker push when a chapter is finished. Self-guards on
+// login + the syncProgress setting and dedupes per session, so a reader can
+// call it freely (e.g. on every settle at the last page) without spamming.
+const pushedRead = new Set();
+export async function syncChapterRead(mangaId, chapterId) {
+  if (!chapterId || pushedRead.has(chapterId)) return;
+  if (!isLoggedIn() || !getConfig().syncProgress) return;
+  pushedRead.add(chapterId);
+  try {
+    await markChaptersRead(mangaId, [chapterId]);
+  } catch (err) {
+    pushedRead.delete(chapterId); // let a later attempt retry
+    logger.warn('failed to push read marker', err);
+  }
+}

package/src/sources/mangadex/normalize.js

@@ -0,0 +1,70 @@
+import { makeManga, makeChapter, globalKey } from '../../domain/shape.js';
+import { MANGADEX } from '../../config.js';
+
+const SOURCE = 'mangadex';
+
+// MangaDex localizes strings as { en: "...", ja: "..." }. Prefer English, then
+// whatever's first.
+function localized(map) {
+  if (!map || typeof map !== 'object') return '';
+  return map.en || map[Object.keys(map)[0]] || '';
+}
+
+export function normalizeManga(entry) {
+  const attr = entry.attributes || {};
+  const rels = entry.relationships || [];
+
+  const cover = rels.find((r) => r.type === 'cover_art');
+  const coverFile = cover?.attributes?.fileName;
+  const coverUrl = coverFile
+    ? `${MANGADEX.uploads}/covers/${entry.id}/${coverFile}.512.jpg`
+    : null;
+
+  const authors = [
+    ...new Set(
+      rels
+        .filter((r) => r.type === 'author' || r.type === 'artist')
+        .map((r) => r.attributes?.name)
+        .filter(Boolean),
+    ),
+  ];
+
+  const altTitles = (attr.altTitles || [])
+    .map((o) => Object.values(o)[0])
+    .filter(Boolean);
+
+  const tags = (attr.tags || [])
+    .map((t) => t.attributes?.name?.en)
+    .filter(Boolean);
+
+  return makeManga({
+    source: SOURCE,
+    id: entry.id,
+    title: localized(attr.title) || altTitles[0] || 'Untitled',
+    altTitles,
+    description: localized(attr.description),
+    authors,
+    status: attr.status || 'unknown',
+    tags,
+    coverUrl,
+    language: attr.originalLanguage || 'en',
+    raw: entry,
+  });
+}
+
+export function normalizeChapter(entry, mangaKey) {
+  const attr = entry.attributes || {};
+  const mangaRel = (entry.relationships || []).find((r) => r.type === 'manga');
+  return makeChapter({
+    source: SOURCE,
+    id: entry.id,
+    mangaKey: mangaKey || (mangaRel ? globalKey(SOURCE, mangaRel.id) : null),
+    number: attr.chapter ?? null,
+    volume: attr.volume ?? null,
+    title: attr.title || '',
+    language: attr.translatedLanguage || 'en',
+    pages: attr.pages ?? null,
+    publishedAt: attr.publishAt ? new Date(attr.publishAt) : null,
+    raw: entry,
+  });
+}

package/src/state/store.js

@@ -0,0 +1,90 @@
+import fs from 'node:fs';
+import { paths, DEFAULT_CONFIG, ensureDirs } from '../config.js';
+import { logger } from '../lib/logger.js';
+
+function readJson(file, fallback) {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch (err) {
+    if (err.code !== 'ENOENT') logger.warn(`failed to read ${file}`, err);
+    return fallback;
+  }
+}
+
+// Write-to-temp + rename so a crash mid-write never corrupts the file.
+function writeJsonAtomic(file, data) {
+  ensureDirs();
+  const tmp = `${file}.${process.pid}.tmp`;
+  fs.writeFileSync(tmp, JSON.stringify(data, null, 2));
+  fs.renameSync(tmp, file);
+}
+
+// ---- Config (user prefs + library paths) -------------------------------
+let config = null;
+export function getConfig() {
+  if (!config) config = { ...DEFAULT_CONFIG, ...readJson(paths.configFile, {}) };
+  return config;
+}
+export function setConfig(patch) {
+  config = { ...getConfig(), ...patch };
+  writeJsonAtomic(paths.configFile, config);
+  return config;
+}
+
+// ---- Reading progress --------------------------------------------------
+// Shape: { [mangaKey]: { source, mangaId, mangaTitle, chapterId, chapterNumber, page, updatedAt } }
+let progress = null;
+function loadProgress() {
+  if (!progress) progress = readJson(paths.progressFile, {});
+  return progress;
+}
+
+// Debounced save — the reader updates progress on every page turn, so coalesce.
+let saveTimer = null;
+function scheduleSave() {
+  clearTimeout(saveTimer);
+  saveTimer = setTimeout(() => writeJsonAtomic(paths.progressFile, progress), 400);
+  saveTimer.unref?.();
+}
+
+export function getProgress(mangaKey) {
+  return loadProgress()[mangaKey] || null;
+}
+export function getAllProgress() {
+  return Object.values(loadProgress()).sort((a, b) => (b.updatedAt || 0) - (a.updatedAt || 0));
+}
+export function setProgress(mangaKey, entry) {
+  loadProgress()[mangaKey] = { ...entry, updatedAt: Date.now() };
+  scheduleSave();
+}
+export function flushProgress() {
+  clearTimeout(saveTimer);
+  if (progress) writeJsonAtomic(paths.progressFile, progress);
+}
+
+// ---- MangaDex credentials (OAuth2 personal client) ---------------------
+// Only the durable secrets live here: the client id/secret and the rotating
+// refresh token. The 15-min access token is kept in memory by auth.js and
+// never written to disk. File is 0600 since it holds a long-lived secret.
+let credentials = null;
+function writeCredentialsAtomic(data) {
+  ensureDirs();
+  const file = paths.credentialsFile;
+  const tmp = `${file}.${process.pid}.tmp`;
+  fs.writeFileSync(tmp, JSON.stringify(data, null, 2), { mode: 0o600 });
+  fs.renameSync(tmp, file);
+  try { fs.chmodSync(file, 0o600); } catch { /* best effort (e.g. Windows) */ }
+}
+export function getCredentials() {
+  if (credentials === null) credentials = readJson(paths.credentialsFile, {});
+  return credentials.refreshToken ? credentials : null;
+}
+export function setCredentials(next) {
+  credentials = { ...next };
+  writeCredentialsAtomic(credentials);
+  return credentials;
+}
+export function clearCredentials() {
+  credentials = {};
+  try { fs.rmSync(paths.credentialsFile, { force: true }); } catch { /* ignore */ }
+}