@chriswiegman/hugo-tools 0.2.1 → 0.3.0

package/src/book.mjs

@@ -1,9 +1,10 @@
 #!/usr/bin/env node
 /**
- * Goodreads → Hugo Books importer (NO covers)
+ * Goodreads → Hugo Books importer
  * - Writes: content/books/<author-last-first>/<title-slug>.md
  * - Front matter:
- *   title, author, rating (0-5), finished ([YYYY-MM-DD...]), links { amazon, openlibrary, goodreads }
+ *   title, author, rating (0-5), finished ([YYYY-MM-DD...]), links { amazon, openlibrary, goodreads },
+ *   reference { isbn, asin }, cover
  * - Review (if any) becomes body content
  * - finished uses Date Read; if blank, Date Added (only for Exclusive Shelf == "read")
  *
@@ -12,11 +13,44 @@
  * - Existing files are matched by Goodreads Book ID first, then ISBN, then title slug.
  * - When a match is found at a different path (title changed in Goodreads), the file is
  *   renamed to the new slug and the title in front matter is updated automatically.
- * - For an existing book file, finished dates are merged; other fields are left untouched
+ * - For an existing book file, finished dates are merged and the rating is updated when the
+ *   Goodreads rating differs from the file's rating — but only when Goodreads has a rating
+ *   (> 0). A Goodreads rating of 0 (unrated) never overwrites a rating already in the file,
+ *   since you may have rated the book only in the markdown. Other fields are left untouched
  *   unless a rename occurs (in which case the title is also updated).
+ * - reference.isbn/asin are backfilled onto existing files that are missing them, but a
+ *   value already present in the file (e.g. entered by hand) is never overwritten.
+ *
+ * Re-reads:
+ * - Goodreads' CSV export only ever contains the *most recent* "Date Read" per book, even
+ *   when "Read Count" shows it was finished more than once. So: if you re-read a book,
+ *   the next export will carry the new completion date, and — since it differs from what's
+ *   already on file — it's automatically merged into `finished` as an additional date
+ *   (nothing is overwritten; dates only ever get added, never replaced or removed).
+ * - What the export can't give you is *earlier* read dates for a book already read more
+ *   than once before this tool started tracking it. When "Read Count" is higher than the
+ *   number of dates on file, the script prints a `NOTE:` line and leaves the file
+ *   untouched — add the missing date(s) to `finished` by hand. The note stops appearing
+ *   once the counts line up.
+ *
+ * ASIN lookup:
+ * - Goodreads exports don't include an ASIN, so it's looked up per ISBN from Open Library,
+ *   then Google Books, and left blank if neither has one. Configure an Amazon Product
+ *   Advertising API key in .hugo-tools.json (amazonPaApi: { accessKey, secretKey, partnerTag })
+ *   to use it as a final fallback.
+ *
+ * Cover art (opt-in):
+ * - Off by default — pass --covers to fetch and save cover art.
+ * - Looked up per ISBN from Open Library's cover API, then Google Books, and left blank if
+ *   neither has one.
+ * - Saved to <coversDir>/<author-slug>/<title-slug>.<ext> (coversDir defaults to
+ *   assets/images/books, configurable via .hugo-tools.json) and referenced from the
+ *   `cover` front matter field as a Hugo URL path.
+ * - Only backfills a blank `cover` field on existing files — a cover already set
+ *   (e.g. entered by hand) is never overwritten.
  *
  * Usage:
- *   node scripts/book.mjs path/to/goodreads.csv
+ *   node scripts/book.mjs path/to/goodreads.csv [--covers]
  *
  * Notes:
  * - This script uses global fetch (Node 18+).
@@ -25,6 +59,7 @@
 import fs from 'node:fs/promises';
 import { existsSync, readFileSync } from 'node:fs';
 import path from 'node:path';
+import { createHash, createHmac } from 'node:crypto';
 
 // -------------------- Config --------------------
 
@@ -42,10 +77,17 @@ try {
 
 const OUTPUT_ROOT = path.join(PROJECT_ROOT, _userConfig.booksDir ?? 'content/books');
 
+// Optional Amazon Product Advertising API credentials for ASIN lookup fallback.
+// Set via .hugo-tools.json: { "amazonPaApi": { "accessKey", "secretKey", "partnerTag" } }
+const AMAZON_PA_CONFIG = _userConfig.amazonPaApi ?? null;
+
+// Project-relative directory cover art is saved under. Set via .hugo-tools.json: { "coversDir" }
+const COVERS_DIR = _userConfig.coversDir ?? 'assets/images/books';
+
 // -------------------- Utilities --------------------
 
 function usageAndExit() {
-	console.error('Usage: node scripts/book.mjs path/to/goodreads.csv');
+	console.error('Usage: node scripts/book.mjs path/to/goodreads.csv [--covers]');
 	process.exit(1);
 }
 
@@ -200,6 +242,24 @@ function keyFor(title, author) {
 	return `${title.trim().toLowerCase()}|${author.trim().toLowerCase()}`;
 }
 
+/**
+ * Strip a UTF-8 BOM if present. Some export tools/editors add one, and it would
+ * otherwise corrupt the first header name (e.g. "\uFEFFBook Id") and fail column detection.
+ */
+function stripBOM(text) {
+	return String(text ?? '').replace(/^\uFEFF/, '');
+}
+
+/**
+ * Goodreads' CSV export only ever includes the most recent "Date Read" per book, even
+ * when "Read Count" shows it was finished more than once — there's no way to recover
+ * earlier read dates from the export alone. Flag books where fewer dates are on record
+ * than the Goodreads read count, as a nudge to add the missing ones to `finished` by hand.
+ */
+function needsReReadDates(readCount, finishedCount) {
+	return Number.isFinite(readCount) && readCount > 1 && finishedCount < readCount;
+}
+
 function goodreadsBookUrl(bookId) {
 	return bookId ? `https://www.goodreads.com/book/show/${bookId}` : '';
 }
@@ -215,6 +275,292 @@ function amazonSearchLink({ isbn13, isbn10, title, author }) {
 	return `https://www.amazon.com/s?k=${encodeURIComponent(query)}`;
 }
 
+// -------------------- ASIN lookup --------------------
+
+function sleep(ms) {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * Open Library sometimes exposes an "amazon" identifier on an edition, which
+ * for Kindle editions is the ASIN.
+ */
+async function lookupAsinFromOpenLibrary(isbn, fetchImpl = fetch) {
+	if (!isbn) return '';
+
+	try {
+		const url = `https://openlibrary.org/api/books?bibkeys=ISBN:${encodeURIComponent(isbn)}&jscmd=data&format=json`;
+		const res = await fetchImpl(url);
+
+		if (!res.ok) return '';
+
+		const data = await res.json();
+		const amazon = data?.[`ISBN:${isbn}`]?.identifiers?.amazon;
+
+		return Array.isArray(amazon) && amazon[0] ? String(amazon[0]).trim().toUpperCase() : '';
+	} catch {
+		return '';
+	}
+}
+
+/**
+ * Google Books occasionally lists a non-ISBN "OTHER" industry identifier that
+ * matches the shape of an ASIN. Best-effort only — most volumes won't have one.
+ */
+async function lookupAsinFromGoogleBooks(isbn, fetchImpl = fetch) {
+	if (!isbn) return '';
+
+	try {
+		const url = `https://www.googleapis.com/books/v1/volumes?q=isbn:${encodeURIComponent(isbn)}`;
+		const res = await fetchImpl(url);
+
+		if (!res.ok) return '';
+
+		const data = await res.json();
+		const identifiers = data?.items?.[0]?.volumeInfo?.industryIdentifiers ?? [];
+
+		for (const id of identifiers) {
+			if (id?.type !== 'OTHER') continue;
+
+			const bare = String(id.identifier || '').trim().toUpperCase().replace(/^[A-Z]+:/, '');
+
+			if (/^[A-Z0-9]{10}$/.test(bare) && bare !== isbn.toUpperCase()) return bare;
+		}
+
+		return '';
+	} catch {
+		return '';
+	}
+}
+
+function hmac(key, data) {
+	return createHmac('sha256', key).update(data, 'utf8').digest();
+}
+
+function sha256Hex(data) {
+	return createHash('sha256').update(data, 'utf8').digest('hex');
+}
+
+function amazonPaApiSignature({ secretKey, region, service, dateStamp, stringToSign }) {
+	const kDate = hmac(`AWS4${secretKey}`, dateStamp);
+	const kRegion = hmac(kDate, region);
+	const kService = hmac(kRegion, service);
+	const kSigning = hmac(kService, 'aws4_request');
+
+	return hmac(kSigning, stringToSign).toString('hex');
+}
+
+/**
+ * Official Amazon Product Advertising API v5 GetItems call, signed with SigV4.
+ * Only attempted when accessKey/secretKey/partnerTag are configured.
+ */
+async function lookupAsinFromAmazonPa(isbn, config, fetchImpl = fetch) {
+	if (!isbn || !config?.accessKey || !config?.secretKey || !config?.partnerTag) return '';
+
+	const host = config.host || 'webservices.amazon.com';
+	const region = config.region || 'us-east-1';
+	const marketplace = config.marketplace || 'www.amazon.com';
+	const service = 'ProductAdvertisingAPI';
+	const target = 'com.amazon.paapi5.v1.ProductAdvertisingAPIv1.GetItems';
+	const uri = '/paapi5/getitems';
+
+	const payload = JSON.stringify({
+		ItemIds: [isbn],
+		ItemIdType: 'ISBN',
+		Resources: ['ItemInfo.Title'],
+		PartnerTag: config.partnerTag,
+		PartnerType: 'Associates',
+		Marketplace: marketplace,
+	});
+
+	const amzDate = new Date().toISOString().replace(/[:-]|\.\d{3}/g, '');
+	const dateStamp = amzDate.slice(0, 8);
+	const canonicalHeaders =
+		`content-encoding:amz-1.0\ncontent-type:application/json; charset=utf-8\nhost:${host}\n` +
+		`x-amz-date:${amzDate}\nx-amz-target:${target}\n`;
+	const signedHeaders = 'content-encoding;content-type;host;x-amz-date;x-amz-target';
+	const canonicalRequest = `POST\n${uri}\n\n${canonicalHeaders}\n${signedHeaders}\n${sha256Hex(payload)}`;
+	const credentialScope = `${dateStamp}/${region}/${service}/aws4_request`;
+	const stringToSign =
+		`AWS4-HMAC-SHA256\n${amzDate}\n${credentialScope}\n${sha256Hex(canonicalRequest)}`;
+	const signature = amazonPaApiSignature({ secretKey: config.secretKey, region, service, dateStamp, stringToSign });
+	const authorization =
+		`AWS4-HMAC-SHA256 Credential=${config.accessKey}/${credentialScope}, ` +
+		`SignedHeaders=${signedHeaders}, Signature=${signature}`;
+
+	try {
+		const res = await fetchImpl(`https://${host}${uri}`, {
+			method: 'POST',
+			headers: {
+				'content-encoding': 'amz-1.0',
+				'content-type': 'application/json; charset=utf-8',
+				host,
+				'x-amz-date': amzDate,
+				'x-amz-target': target,
+				authorization,
+			},
+			body: payload,
+		});
+
+		if (!res.ok) return '';
+
+		const data = await res.json();
+		const asin = data?.ItemsResult?.Items?.[0]?.ASIN;
+
+		return asin ? String(asin).trim().toUpperCase() : '';
+	} catch {
+		return '';
+	}
+}
+
+/**
+ * Look up an ASIN for an ISBN, trying free sources first (Open Library, then
+ * Google Books) and falling back to the Amazon Product Advertising API only
+ * when it's configured. Returns '' when no source has a match.
+ */
+async function lookupAsin(isbn, amazonPaConfig, cache, fetchImpl = fetch) {
+	if (!isbn) return '';
+
+	if (cache?.has(isbn)) return cache.get(isbn);
+
+	let asin = await lookupAsinFromOpenLibrary(isbn, fetchImpl);
+
+	if (!asin) {
+		await sleep(150);
+		asin = await lookupAsinFromGoogleBooks(isbn, fetchImpl);
+	}
+
+	if (!asin && amazonPaConfig) {
+		await sleep(150);
+		asin = await lookupAsinFromAmazonPa(isbn, amazonPaConfig, fetchImpl);
+	}
+
+	if (cache) cache.set(isbn, asin);
+
+	return asin;
+}
+
+// -------------------- Cover art (opt-in) --------------------
+
+const IMAGE_EXT_BY_CONTENT_TYPE = {
+	'image/jpeg': '.jpg',
+	'image/jpg': '.jpg',
+	'image/png': '.png',
+	'image/webp': '.webp',
+	'image/gif': '.gif',
+};
+
+function extFromContentType(contentType) {
+	const bare = String(contentType || '').split(';')[0].trim().toLowerCase();
+
+	return IMAGE_EXT_BY_CONTENT_TYPE[bare] || '.jpg';
+}
+
+/**
+ * Convert a project-relative asset path (e.g. "assets/images/books/king-stephen/it.jpg")
+ * into the Hugo-served URL path, mirroring pick-image's convention of stripping the
+ * `assets/` prefix.
+ */
+function coverUrlFromAssetPath(assetPath) {
+	const rel = assetPath.split(path.sep).join('/').replace(/^assets\//, '');
+
+	return `/${rel}`;
+}
+
+/**
+ * Open Library's cover API serves the image directly at a predictable URL keyed by
+ * ISBN. `default=false` makes it 404 instead of returning a placeholder when there's
+ * no cover, so a non-OK response reliably means "no cover here."
+ */
+async function fetchOpenLibraryCover(isbn, fetchImpl = fetch) {
+	if (!isbn) return null;
+
+	try {
+		const url = `https://covers.openlibrary.org/b/isbn/${encodeURIComponent(isbn)}-L.jpg?default=false`;
+		const res = await fetchImpl(url);
+
+		if (!res.ok) return null;
+
+		const contentType = res.headers?.get?.('content-type') || 'image/jpeg';
+
+		if (!contentType.startsWith('image/')) return null;
+
+		const buffer = Buffer.from(await res.arrayBuffer());
+
+		if (buffer.length === 0) return null;
+
+		return { buffer, contentType };
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Fallback cover source: Google Books' volume thumbnail, used when Open Library has none.
+ */
+async function fetchGoogleBooksCover(isbn, fetchImpl = fetch) {
+	if (!isbn) return null;
+
+	try {
+		const url = `https://www.googleapis.com/books/v1/volumes?q=isbn:${encodeURIComponent(isbn)}`;
+		const res = await fetchImpl(url);
+
+		if (!res.ok) return null;
+
+		const data = await res.json();
+		const imageLinks = data?.items?.[0]?.volumeInfo?.imageLinks;
+		const thumbnail = imageLinks?.thumbnail || imageLinks?.smallThumbnail;
+
+		if (!thumbnail) return null;
+
+		const imgRes = await fetchImpl(thumbnail.replace(/^http:/, 'https:'));
+
+		if (!imgRes.ok) return null;
+
+		const contentType = imgRes.headers?.get?.('content-type') || 'image/jpeg';
+
+		if (!contentType.startsWith('image/')) return null;
+
+		const buffer = Buffer.from(await imgRes.arrayBuffer());
+
+		if (buffer.length === 0) return null;
+
+		return { buffer, contentType };
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Look up cover art for an ISBN, trying Open Library first and Google Books second.
+ * Returns null when neither source has one.
+ */
+async function fetchBookCover(isbn, fetchImpl = fetch) {
+	if (!isbn) return null;
+
+	const openLibrary = await fetchOpenLibraryCover(isbn, fetchImpl);
+
+	if (openLibrary) return openLibrary;
+
+	await sleep(150);
+	return fetchGoogleBooksCover(isbn, fetchImpl);
+}
+
+/**
+ * Write cover image bytes to `<coversDir>/<authorDir>/<slug><ext>` (relative to
+ * `projectRoot`) and return the Hugo URL path to store in front matter.
+ */
+async function saveCover(coversDir, authorDir, slug, cover, projectRoot = PROJECT_ROOT) {
+	const ext = extFromContentType(cover.contentType);
+	const relPath = path.join(coversDir, authorDir, `${slug}${ext}`);
+	const absPath = path.join(projectRoot, relPath);
+
+	await fs.mkdir(path.dirname(absPath), { recursive: true });
+	await fs.writeFile(absPath, cover.buffer);
+
+	return coverUrlFromAssetPath(relPath);
+}
+
 /**
  * Use "Author l-f" (e.g. "Baldacci, David") → folder "baldacci-david"
  */
@@ -244,11 +590,13 @@ function authorDirFromAuthorLF(authorLF) {
  *     - "YYYY-MM-DD"
  *     - "YYYY-MM-DD"
  * - finished: "YYYY-MM-DD"   (legacy scalar; included as one date)
+ *
+ * Also extracts the existing `rating:` value (or null if absent/unparseable).
  */
 function parseExistingMarkdown(md) {
 	const m = md.match(/^---\s*\n([\s\S]*?)\n---\s*\n?([\s\S]*)$/);
 
-	if (!m) return { finished: [] };
+	if (!m) return { finished: [], rating: null };
 
 	const fm = m[1];
 	const lines = fm.split('\n');
@@ -280,7 +628,18 @@ function parseExistingMarkdown(md) {
 		}
 	}
 
-	return { finished: uniqSortedDates(finished) };
+	let rating = null;
+
+	for (const line of lines) {
+		const mm = line.match(/^rating:\s*(\d+)\s*$/);
+
+		if (mm) {
+			rating = Number(mm[1]);
+			break;
+		}
+	}
+
+	return { finished: uniqSortedDates(finished), rating };
 }
 
 async function fileExists(p) {
@@ -334,6 +693,116 @@ function updateTitleInFrontMatter(md, newTitle) {
 	return md.replace(/^title:.*$/m, `title: "${escapeYAMLString(newTitle)}"`);
 }
 
+/**
+ * Update the rating field in front matter, leaving everything else untouched.
+ */
+function updateRatingInFrontMatter(md, newRating) {
+	return md.replace(/^rating:.*$/m, `rating: ${newRating}`);
+}
+
+/**
+ * Extract the existing `reference: { isbn, asin }` values from a file's front matter.
+ * Returns { isbn: '', asin: '' } when the block (or either field) is absent.
+ */
+function parseExistingReference(md) {
+	const m = md.match(/^---\s*\n([\s\S]*?)\n---\s*\n?([\s\S]*)$/);
+
+	if (!m) return { isbn: '', asin: '' };
+
+	const lines = m[1].split('\n');
+	let isbn = '';
+	let asin = '';
+
+	for (let i = 0; i < lines.length; i++) {
+		if (lines[i].trim() !== 'reference:') continue;
+
+		for (let j = i + 1; j < lines.length; j++) {
+			const line = lines[j];
+
+			if (/^[A-Za-z0-9_-]+:/.test(line)) break; // new top-level key
+
+			const isbnMatch = line.match(/^\s*isbn:\s*"?([^"\n]*)"?\s*$/);
+
+			if (isbnMatch) isbn = isbnMatch[1].trim();
+
+			const asinMatch = line.match(/^\s*asin:\s*"?([^"\n]*)"?\s*$/);
+
+			if (asinMatch) asin = asinMatch[1].trim();
+		}
+		break;
+	}
+
+	return { isbn, asin };
+}
+
+/**
+ * Insert or replace the `reference:` block in front matter, leaving everything
+ * else untouched. Inserts a new block just before the closing `---` when none exists.
+ */
+function upsertReferenceInFrontMatter(md, { isbn, asin }) {
+	const block = [
+		'reference:',
+		`  isbn: "${escapeYAMLString(isbn)}"`,
+		`  asin: "${escapeYAMLString(asin)}"`,
+	];
+	const lines = md.split('\n');
+	const refIdx = lines.findIndex((l) => /^reference:\s*$/.test(l));
+
+	if (refIdx !== -1) {
+		let endIdx = refIdx + 1;
+
+		while (endIdx < lines.length && /^\s/.test(lines[endIdx])) {
+			endIdx++;
+		}
+		return [...lines.slice(0, refIdx), ...block, ...lines.slice(endIdx)].join('\n');
+	}
+
+	const closingIdx = lines.findIndex((l, i) => i > 0 && l.trim() === '---');
+
+	if (closingIdx === -1) {
+		console.warn('  WARNING: could not locate front matter to insert \'reference:\' block — file left unchanged');
+		return md;
+	}
+
+	return [...lines.slice(0, closingIdx), ...block, ...lines.slice(closingIdx)].join('\n');
+}
+
+/**
+ * Extract the existing scalar `cover:` value from a file's front matter.
+ * Returns '' when the field is absent.
+ */
+function parseExistingCover(md) {
+	const m = md.match(/^---\s*\n([\s\S]*?)\n---\s*\n?([\s\S]*)$/);
+
+	if (!m) return '';
+
+	const mm = m[1].match(/^cover:\s*"?([^"\n]*)"?\s*$/m);
+
+	return mm ? mm[1].trim() : '';
+}
+
+/**
+ * Insert or replace the scalar `cover:` field in front matter, leaving everything
+ * else untouched. Inserts a new line just before the closing `---` when absent.
+ */
+function upsertCoverInFrontMatter(md, coverPath) {
+	const line = `cover: "${escapeYAMLString(coverPath)}"`;
+
+	if (/^cover:.*$/m.test(md)) {
+		return md.replace(/^cover:.*$/m, line);
+	}
+
+	const lines = md.split('\n');
+	const closingIdx = lines.findIndex((l, i) => i > 0 && l.trim() === '---');
+
+	if (closingIdx === -1) {
+		console.warn('  WARNING: could not locate front matter to insert \'cover:\' field — file left unchanged');
+		return md;
+	}
+
+	return [...lines.slice(0, closingIdx), line, ...lines.slice(closingIdx)].join('\n');
+}
+
 // -------------------- Existing-file index --------------------
 
 /**
@@ -462,7 +931,7 @@ async function removeIfEmpty(dirPath) {
 
 // -------------------- Writing front matter --------------------
 
-function toFrontMatter({ title, author, rating, finished, links }) {
+function toFrontMatter({ title, author, rating, finished, links, reference, cover }) {
 	const lines = [];
 
 	lines.push('---');
@@ -476,6 +945,13 @@ function toFrontMatter({ title, author, rating, finished, links }) {
 	lines.push(`  amazon: "${escapeYAMLString(links.amazon)}"`);
 	lines.push(`  openlibrary: "${escapeYAMLString(links.openlibrary)}"`);
 	lines.push(`  goodreads: "${escapeYAMLString(links.goodreads)}"`);
+
+	lines.push('reference:');
+	lines.push(`  isbn: "${escapeYAMLString(reference?.isbn ?? '')}"`);
+	lines.push(`  asin: "${escapeYAMLString(reference?.asin ?? '')}"`);
+
+	lines.push(`cover: "${escapeYAMLString(cover ?? '')}"`);
+
 	lines.push('---');
 	return lines.join('\n');
 }
@@ -494,11 +970,13 @@ async function main() {
 		process.exit(1);
 	}
 
-	const csvPath = process.argv[2];
+	const argv = process.argv.slice(2);
+	const withCovers = argv.includes('--covers');
+	const csvPath = argv.find((a) => a && !a.startsWith('--'));
 
 	if (!csvPath) usageAndExit();
 
-	const csvText = await fs.readFile(csvPath, 'utf8');
+	const csvText = stripBOM(await fs.readFile(csvPath, 'utf8'));
 	const rows = parseCSV(csvText);
 
 	if (rows.length < 2) {
@@ -638,11 +1116,18 @@ async function main() {
 	let mergedExisting = 0;
 	let renamedFiles = 0;
 	let skippedUnchanged = 0;
+	let ratingsUpdated = 0;
+	let referencesUpdated = 0;
+	let coversFetched = 0;
+	let reReadsFlagged = 0;
+
+	const asinCache = new Map();
 
 	for (const b of bookList) {
 		const authorDir = authorDirFromAuthorLF(b.authorLF);
 		const filename = `${slugify(b.title)}.md`;
 		const outPath = path.join(OUTPUT_ROOT, authorDir, filename);
+		const isbnBest = b.isbn13 || b.isbn10;
 
 		const existingPath = await findExistingFile(b, outPath, index);
 
@@ -651,14 +1136,56 @@ async function main() {
 
 			// Read the existing file
 			const existingContent = await fs.readFile(existingPath, 'utf8');
-			const { finished: existingFinished } = parseExistingMarkdown(existingContent);
+			const { finished: existingFinished, rating: existingRating } = parseExistingMarkdown(existingContent);
 			const finishedMerged = uniqSortedDates([...existingFinished, ...b.finished]);
 
 			const hasNewDates =
 				finishedMerged.length !== existingFinished.length ||
         finishedMerged.some((d, i) => d !== existingFinished[i]);
 
-			if (!titleChanged && !hasNewDates) {
+			// Only let Goodreads override the file's rating when Goodreads actually has one (> 0).
+			// A rating of 0 usually means "not rated on Goodreads" — the file may carry a rating
+			// entered by hand there instead, so leave it alone rather than clobbering it with 0.
+			const hasRatingChange = b.rating > 0 && existingRating !== null && b.rating !== existingRating;
+
+			// Never clobber an isbn/asin already present in the file — only fill blanks.
+			const { isbn: existingIsbn, asin: existingAsin } = parseExistingReference(existingContent);
+			const finalIsbn = existingIsbn || isbnBest || '';
+			let finalAsin = existingAsin;
+
+			if (!finalAsin && finalIsbn) {
+				finalAsin = await lookupAsin(finalIsbn, AMAZON_PA_CONFIG, asinCache);
+			}
+
+			const hasReferenceChange = finalIsbn !== existingIsbn || finalAsin !== existingAsin;
+
+			// Only fetch/backfill cover art when explicitly requested, and only into a blank field.
+			const existingCover = parseExistingCover(existingContent);
+			let finalCover = existingCover;
+
+			if (withCovers && !finalCover && finalIsbn) {
+				const coverResult = await fetchBookCover(finalIsbn);
+
+				if (coverResult) {
+					finalCover = await saveCover(COVERS_DIR, authorDir, slugify(b.title), coverResult);
+				}
+			}
+
+			const hasCoverChange = finalCover !== existingCover;
+
+			// Independent of whether anything else changed — surfaced every run until resolved.
+			if (needsReReadDates(b.readCount, finishedMerged.length)) {
+				reReadsFlagged++;
+
+				const rel = path.relative(OUTPUT_ROOT, existingPath);
+
+				console.log(
+					`  NOTE: ${rel} shows ${b.readCount}x read on Goodreads but only ${finishedMerged.length} ` +
+					'date(s) on file — Goodreads only exports the latest read date, so add earlier ones to \'finished\' by hand.',
+				);
+			}
+
+			if (!titleChanged && !hasNewDates && !hasRatingChange && !hasReferenceChange && !hasCoverChange) {
 				skippedUnchanged++;
 				continue;
 			}
@@ -670,6 +1197,33 @@ async function main() {
 				patched = replaceFinishedBlock(patched, finishedMerged);
 			}
 
+			if (hasRatingChange) {
+				patched = updateRatingInFrontMatter(patched, b.rating);
+				ratingsUpdated++;
+
+				const rel = path.relative(OUTPUT_ROOT, existingPath);
+
+				console.log(`  RATING UPDATED: ${rel} (${existingRating} -> ${b.rating})`);
+			}
+
+			if (hasReferenceChange) {
+				patched = upsertReferenceInFrontMatter(patched, { isbn: finalIsbn, asin: finalAsin });
+				referencesUpdated++;
+
+				const rel = path.relative(OUTPUT_ROOT, existingPath);
+
+				console.log(`  REFERENCE UPDATED: ${rel} (isbn: "${finalIsbn}", asin: "${finalAsin}")`);
+			}
+
+			if (hasCoverChange) {
+				patched = upsertCoverInFrontMatter(patched, finalCover);
+				coversFetched++;
+
+				const rel = path.relative(OUTPUT_ROOT, existingPath);
+
+				console.log(`  COVER ADDED: ${rel} (${finalCover})`);
+			}
+
 			if (titleChanged) {
 				patched = updateTitleInFrontMatter(patched, b.title);
 			}
@@ -698,7 +1252,15 @@ async function main() {
 			createdNew++;
 
 			const finishedMerged = uniqSortedDates(b.finished);
-			const isbnBest = b.isbn13 || b.isbn10;
+
+			if (needsReReadDates(b.readCount, finishedMerged.length)) {
+				reReadsFlagged++;
+
+				console.log(
+					`  NOTE: "${b.title}" shows ${b.readCount}x read on Goodreads but only ${finishedMerged.length} ` +
+					'date(s) on file — Goodreads only exports the latest read date, so add earlier ones to \'finished\' by hand.',
+				);
+			}
 
 			const links = {
 				amazon: amazonSearchLink({ isbn13: b.isbn13, isbn10: b.isbn10, title: b.title, author: b.author }),
@@ -706,12 +1268,32 @@ async function main() {
 				goodreads: goodreadsBookUrl(b.bookId),
 			};
 
+			const reference = {
+				isbn: isbnBest,
+				asin: isbnBest ? await lookupAsin(isbnBest, AMAZON_PA_CONFIG, asinCache) : '',
+			};
+
+			let cover = '';
+
+			if (withCovers && isbnBest) {
+				const coverResult = await fetchBookCover(isbnBest);
+
+				if (coverResult) {
+					cover = await saveCover(COVERS_DIR, authorDir, slugify(b.title), coverResult);
+					coversFetched++;
+
+					console.log(`  COVER SAVED: ${cover}`);
+				}
+			}
+
 			const fm = toFrontMatter({
 				title: b.title,
 				author: b.author,
 				rating: b.rating,
 				finished: finishedMerged,
 				links,
+				reference,
+				cover,
 			});
 
 			const bodyToWrite = b.review ? `\n\n${b.review}\n` : '\n';
@@ -746,7 +1328,11 @@ async function main() {
       `  New files created:       ${createdNew}\n` +
       `  Existing files updated:  ${mergedExisting}\n` +
       `  Files renamed:           ${renamedFiles}\n` +
+      `  Ratings updated:         ${ratingsUpdated}\n` +
+      `  References updated:      ${referencesUpdated}\n` +
+      `  Covers fetched:          ${coversFetched}${withCovers ? '' : ' (pass --covers to fetch cover art)'}\n` +
       `  Existing files skipped:  ${skippedUnchanged}\n` +
+      `  Rereads needing dates:   ${reReadsFlagged}${reReadsFlagged ? ' (see NOTE lines above)' : ''}\n` +
       `  Content output:          ${OUTPUT_ROOT}\n`,
 	);
 }
@@ -771,6 +1357,8 @@ export {
 	uniqSortedDates,
 	authorDirFromAuthorLF,
 	keyFor,
+	needsReReadDates,
+	stripBOM,
 	goodreadsBookUrl,
 	openLibraryIsbnUrl,
 	amazonSearchLink,
@@ -778,9 +1366,24 @@ export {
 	parseExistingMarkdown,
 	replaceFinishedBlock,
 	updateTitleInFrontMatter,
+	updateRatingInFrontMatter,
+	parseExistingReference,
+	upsertReferenceInFrontMatter,
+	parseExistingCover,
+	upsertCoverInFrontMatter,
 	extractGoodreadsId,
 	extractFileIsbns,
 	toFrontMatter,
 	buildExistingIndex,
 	findExistingFile,
+	lookupAsinFromOpenLibrary,
+	lookupAsinFromGoogleBooks,
+	lookupAsinFromAmazonPa,
+	lookupAsin,
+	extFromContentType,
+	coverUrlFromAssetPath,
+	fetchOpenLibraryCover,
+	fetchGoogleBooksCover,
+	fetchBookCover,
+	saveCover,
 };