backdraw 0.0.0-stage → 2.1.1

package/lib/collection-store.js

@@ -0,0 +1,288 @@
+'use strict';
+// Reference collections on disk. Every function takes the collections folder (root) first, so the
+// tests can use a temporary one. Layout: <root>/<folder>/collection.json, the images next to it and
+// thumbs/<file>.jpg. Folder and file names are always made here, never taken from a request, and
+// every path is checked to stay inside root.
+const crypto = require('crypto');
+const fs = require('fs');
+const path = require('path');
+const { sniffExt } = require('./naming');
+const { MAX_COLLECTION_BYTES } = require('./limits');
+const c = require('./collections');
+
+const MANIFEST = 'collection.json';
+const THUMBS = 'thumbs';
+const MAX_THUMB_BYTES = 256 * 1024;
+const SMALL_ORIGINAL = 200 * 1024; // shown as its own thumbnail when it has none
+const THUMB_PAGE = 600000; // base64 chars of thumbnails per answer: Chrome caps host->extension messages at 1 MB
+const MIME = { png: 'image/png', jpg: 'image/jpeg', webp: 'image/webp', gif: 'image/gif' };
+const PNG_HEAD = Buffer.from('89504e470d0a1a0a0000000d49484452', 'hex');
+
+function storeError(message, code) { return Object.assign(new Error(message), { code }); }
+
+function inside(root, ...parts) {
+  const p = path.join(root, ...parts);
+  if (!c.isInside(root, p)) throw storeError('That path is outside the collections folder.', 'BAD_REQUEST');
+  return p;
+}
+
+function readManifest(dir) {
+  try {
+    const m = JSON.parse(fs.readFileSync(path.join(dir, MANIFEST), 'utf8'));
+    return m && typeof m === 'object' && !Array.isArray(m) ? m : null;
+  } catch { return null; }
+}
+
+function writeManifest(dir, m) {
+  const file = path.join(dir, MANIFEST);
+  const tmp = `${file}.${process.pid}.tmp`;
+  fs.writeFileSync(tmp, JSON.stringify(m, null, 2));
+  fs.renameSync(tmp, file);
+}
+
+// Entries a hand-edited manifest may hold that point anywhere else are left out everywhere.
+const entries = m => (Array.isArray(m.images) ? m.images : []).filter(im => im && c.isPlainFile(im.file));
+// The folder sits in Pictures, so an image may be deleted by hand: such an entry is not listed,
+// counted or attached any more.
+const present = (dir, m) => entries(m).filter(im => fs.existsSync(path.join(dir, im.file)));
+const dim = v => (Number.isInteger(v) && v > 0 && v <= 100000 ? v : null);
+// data: URLs can be megabytes long; only their type is worth keeping.
+const cleanUrl = u => (typeof u !== 'string' || !u ? null : /^data:/i.test(u) ? u.slice(0, Math.min(u.indexOf(',') + 1 || 64, 64)) : u.slice(0, 2048));
+
+function view(root, folder, m) {
+  const dir = path.join(root, folder);
+  const images = c.newestFirst(present(dir, m)).map(im => ({
+    file: im.file, path: path.join(dir, im.file), sourceUrl: im.sourceUrl || null, pageUrl: im.pageUrl || null,
+    addedAt: im.addedAt || null, width: im.width || null, height: im.height || null, bytes: im.bytes || null,
+  }));
+  return {
+    name: c.validateName(m.name).name || folder, folder, path: dir, count: images.length,
+    createdAt: m.createdAt || null, updatedAt: m.updatedAt || m.createdAt || null, images,
+  };
+}
+
+// Every collection, most recently changed first; images newest first.
+function list(root) {
+  let dirs;
+  try { dirs = fs.readdirSync(root, { withFileTypes: true }); } catch (e) { if (e.code === 'ENOENT') return []; throw e; }
+  return dirs.filter(d => d.isDirectory())
+    .map(d => { const m = readManifest(path.join(root, d.name)); return m && view(root, d.name, m); })
+    .filter(Boolean)
+    .sort((a, b) => String(b.updatedAt || '').localeCompare(String(a.updatedAt || '')) || a.name.localeCompare(b.name));
+}
+
+// loose: also match a loosely written name (for generating); changes only take an exact or
+// differently-cased name.
+function find(root, name, loose = true) {
+  const all = list(root);
+  const { collection, error, ties } = c.findCollection(all, name, { loose });
+  if (collection) return collection;
+  if (error === 'AMBIGUOUS') throw storeError(`"${name}" matches several collections: ${ties.map(x => `"${x.name}"`).join(', ')}. Use the exact name.`, 'AMBIGUOUS');
+  throw storeError(`No reference collection matches "${name}". Available collections: ${all.map(x => `"${x.name}"`).join(', ') || '(none)'}`, 'NOT_FOUND');
+}
+
+function uniqueFolder(root, name) {
+  const base = c.safeFolderName(name);
+  for (let n = 1; ; n++) {
+    const folder = n === 1 ? base : c.safeFolderName(`${c.cut(base, c.MAX_NAME - String(n).length - 1)} ${n}`);
+    if (!fs.existsSync(inside(root, folder))) return folder;
+  }
+}
+
+// The number after the highest one in the collection, and never a file that is already there.
+function nextFile(dir, images, srcUrl, ext, name) {
+  let n = images.reduce((max, im) => Math.max(max, parseInt(im.file, 10) || 0), 0);
+  for (;;) {
+    const file = c.fileNameFor(++n, srcUrl, ext, name);
+    if (!fs.existsSync(path.join(dir, file))) return file;
+  }
+}
+
+// A full signature, not just the first two or three bytes (lib/naming.js sniffExt is enough for
+// images ChatGPT made, not for bytes from any web page).
+function imageExt(b) {
+  const at = (from, to) => b.subarray(from, to).toString('latin1');
+  if (b.subarray(0, 16).equals(PNG_HEAD)) return 'png'; // signature and the IHDR chunk that must come first
+  if (b[0] === 0xff && b[1] === 0xd8 && b[2] === 0xff) return 'jpg';
+  if (at(0, 6) === 'GIF87a' || at(0, 6) === 'GIF89a') return 'gif';
+  if (at(0, 4) === 'RIFF' && at(8, 12) === 'WEBP' && /^VP8[ LX]$/.test(at(12, 16))) return 'webp';
+  return null;
+}
+
+// The bytes decide what the file is, whatever mime the caller claims.
+function decodeImage(data) {
+  const tooLarge = storeError(`The image is larger than ${MAX_COLLECTION_BYTES / 1024 / 1024} MB.`, 'TOO_LARGE');
+  if (typeof data !== 'string' || !data) throw storeError('No image data was sent.', 'BAD_REQUEST');
+  if (data.length > Math.ceil(MAX_COLLECTION_BYTES / 3) * 4 + 4) throw tooLarge;
+  const buf = Buffer.from(data, 'base64');
+  if (buf.length > MAX_COLLECTION_BYTES) throw tooLarge;
+  if (buf.length < 24 || !imageExt(buf)) throw storeError('Only png, jpeg, webp and gif images can be saved.', 'BAD_REQUEST');
+  return buf;
+}
+
+function decodeThumb(data) {
+  if (typeof data !== 'string' || !data || data.length > Math.ceil(MAX_THUMB_BYTES / 3) * 4) return null;
+  const buf = Buffer.from(data, 'base64');
+  return buf.length >= 24 && imageExt(buf) === 'jpg' ? buf : null;
+}
+
+// p: { collection, create, data (base64), sourceUrl, pageUrl, thumb (base64 jpeg), width, height }.
+// The same bytes twice in one collection are kept once (duplicate: true). fileName: the host's own
+// name for the file (outside p, so a request from the extension can never set it).
+function add(root, p, now = new Date(), { fileName = '' } = {}) {
+  const { name, error } = c.validateName(p.collection);
+  if (error) throw storeError(error, 'BAD_REQUEST');
+  const buf = decodeImage(p.data);
+  const found = c.findCollection(list(root), name, { loose: false });
+  if (found.error === 'AMBIGUOUS') throw storeError(`"${name}" matches several collections; use the exact name.`, 'AMBIGUOUS');
+  if (found.error && !p.create) throw storeError(`There is no collection named "${name}".`, 'NOT_FOUND');
+  const stamp = now.toISOString();
+  const folder = found.collection ? found.collection.folder : uniqueFolder(root, name);
+  const dir = inside(root, folder);
+  let m = found.collection && readManifest(dir);
+  if (!m) {
+    fs.mkdirSync(dir, { recursive: true });
+    m = { name, createdAt: stamp, updatedAt: stamp, images: [] };
+  }
+  if (!Array.isArray(m.images)) m.images = [];
+  const sha256 = crypto.createHash('sha256').update(buf).digest('hex');
+  const same = present(dir, m).find(im => im.sha256 === sha256);
+  if (same) return { name: m.name, folder, file: same.file, count: present(dir, m).length, created: false, duplicate: true };
+  const file = nextFile(dir, entries(m), p.sourceUrl, imageExt(buf), fileName);
+  fs.writeFileSync(inside(root, folder, file), buf, { flag: 'wx' });
+  const thumb = decodeThumb(p.thumb);
+  if (thumb) {
+    fs.mkdirSync(inside(root, folder, THUMBS), { recursive: true });
+    fs.writeFileSync(inside(root, folder, THUMBS, `${file}.jpg`), thumb);
+  }
+  m.images.push({
+    file, sourceUrl: cleanUrl(p.sourceUrl), pageUrl: cleanUrl(p.pageUrl), addedAt: stamp,
+    bytes: buf.length, width: dim(p.width), height: dim(p.height), sha256,
+  });
+  m.updatedAt = stamp;
+  writeManifest(dir, m);
+  return { name: m.name, folder, file, count: present(dir, m).length, created: !found.collection, duplicate: false };
+}
+
+// Renames the folder too; refuses a name another collection already has.
+function rename(root, name, newName, now = new Date()) {
+  const v = c.validateName(newName);
+  if (v.error) throw storeError(v.error, 'BAD_REQUEST');
+  const col = find(root, name, false);
+  const taken = c.findCollection(list(root).filter(x => x.folder !== col.folder), v.name, { loose: false });
+  if (!taken.error || taken.error === 'AMBIGUOUS') throw storeError(`A collection named "${v.name}" already exists.`, 'EXISTS');
+  let folder = col.folder;
+  const wanted = c.safeFolderName(v.name);
+  if (wanted !== folder) {
+    // A change of case only is the same folder on Windows: rename it in place.
+    folder = wanted.toLowerCase() === folder.toLowerCase() ? wanted : uniqueFolder(root, v.name);
+    fs.renameSync(inside(root, col.folder), inside(root, folder));
+  }
+  const dir = inside(root, folder);
+  const m = readManifest(dir) || { images: [] };
+  Object.assign(m, { name: v.name, updatedAt: now.toISOString() });
+  writeManifest(dir, m);
+  return { name: v.name, oldName: col.name, folder, path: dir };
+}
+
+function unlinkIfThere(file) {
+  try { fs.unlinkSync(file); return true; } catch (e) { if (e.code === 'ENOENT') return false; throw e; }
+}
+
+function rmdirIfEmpty(dir) {
+  try { if (!fs.readdirSync(dir).length) fs.rmdirSync(dir); } catch {}
+}
+
+// Deletes only what the collection itself wrote (its images, their thumbnails and the manifest), then
+// the folders if they are empty. Anything else is left and reported. Images that could not be
+// deleted (e.g. open in another program) stay in the manifest; a thumbnail that stays is only reported.
+function remove(root, name) {
+  const col = find(root, name, false);
+  const dir = inside(root, col.folder);
+  const m = readManifest(dir) || {};
+  let deleted = 0;
+  const failed = [];
+  const kept = [];
+  for (const im of entries(m)) {
+    try {
+      if (unlinkIfThere(inside(root, col.folder, im.file))) deleted++;
+    } catch (e) {
+      failed.push(`${im.file} (${e.code || e.message})`);
+      kept.push(im);
+      continue; // its thumbnail stays with it
+    }
+    try { unlinkIfThere(inside(root, col.folder, THUMBS, `${im.file}.jpg`)); } catch (e) { failed.push(`${THUMBS}/${im.file}.jpg (${e.code || e.message})`); }
+  }
+  if (kept.length) {
+    m.images = kept;
+    writeManifest(dir, m);
+  } else {
+    rmdirIfEmpty(inside(root, col.folder, THUMBS));
+    unlinkIfThere(inside(root, col.folder, MANIFEST));
+    rmdirIfEmpty(dir);
+  }
+  let left = [];
+  try { left = fs.readdirSync(dir); } catch {}
+  return { name: col.name, folder: col.folder, path: dir, deleted, left, failed };
+}
+
+function removeImage(root, name, file, now = new Date()) {
+  const col = find(root, name, false);
+  const dir = inside(root, col.folder);
+  const m = readManifest(dir) || {};
+  const images = Array.isArray(m.images) ? m.images : [];
+  const i = c.isPlainFile(file) ? images.findIndex(im => im && im.file === file) : -1;
+  if (i < 0) throw storeError(`Collection "${col.name}" has no image "${file}".`, 'NOT_FOUND');
+  unlinkIfThere(inside(root, col.folder, file));
+  try { unlinkIfThere(inside(root, col.folder, THUMBS, `${file}.jpg`)); } catch {}
+  images.splice(i, 1);
+  m.images = images;
+  m.updatedAt = now.toISOString();
+  writeManifest(dir, m);
+  return { name: col.name, file, count: present(dir, m).length };
+}
+
+function readThumb(root, folder, im) {
+  try {
+    const buf = fs.readFileSync(inside(root, folder, THUMBS, `${im.file}.jpg`));
+    if (buf.length <= MAX_THUMB_BYTES) return { data: buf.toString('base64'), mime: 'image/jpeg' };
+  } catch {}
+  try {
+    const file = inside(root, folder, im.file);
+    if (fs.statSync(file).size <= SMALL_ORIGINAL) {
+      const buf = fs.readFileSync(file);
+      const ext = sniffExt(buf);
+      if (MIME[ext]) return { data: buf.toString('base64'), mime: MIME[ext] };
+    }
+  } catch {}
+  return { data: null, mime: null };
+}
+
+// Thumbnails newest first, a page at a time (next: the offset to ask for, or null at the end).
+function thumbs(root, name, offset = 0, budget = THUMB_PAGE) {
+  const col = find(root, name, false);
+  const out = [];
+  let size = 0;
+  let i = Math.max(0, Math.floor(Number(offset) || 0));
+  for (; i < col.images.length; i++) {
+    const im = col.images[i];
+    const t = readThumb(root, col.folder, im);
+    const len = t.data ? t.data.length : 0;
+    if (out.length && size + len > budget) break;
+    size += len;
+    out.push({ file: im.file, width: im.width, height: im.height, ...t });
+  }
+  return { name: col.name, total: col.images.length, thumbs: out, next: i < col.images.length ? i : null };
+}
+
+// An image of a collection (from list/find) as a reference for a job.
+function readImage(root, col, im) {
+  const file = inside(root, col.folder, im.file);
+  let buf;
+  try { buf = fs.readFileSync(file); } catch (e) {
+    throw storeError(`Cannot read ${im.file} from collection "${col.name}" (${e.code || e.message}).`, 'NOT_FOUND');
+  }
+  return { name: im.file, mime: MIME[sniffExt(buf)] || 'image/png', data: buf.toString('base64') };
+}
+
+module.exports = { MANIFEST, THUMBS, THUMB_PAGE, list, find, add, rename, remove, removeImage, thumbs, readImage };

package/lib/collections.js

@@ -0,0 +1,192 @@
+'use strict';
+// Reference collections, the pure part: names, folder and file names, path checks, lookups, which
+// images a job attaches and the MCP listing. The file system side is lib/collection-store.js.
+const path = require('path');
+const { slugify } = require('./naming');
+const { normName } = require('./projects');
+const { MAX_REFS, MAX_REF_BYTES, MAX_REFS_TOTAL_BYTES } = require('./limits');
+
+const MAX_NAME = 64;
+const IMAGE_EXTS = ['png', 'jpg', 'webp', 'gif'];
+// The only host methods the extension may call over its native port ({type: 'call'}).
+const EXTENSION_METHODS = new Set([
+  'list_collections', 'collection_add', 'rename_collection', 'delete_collection', 'delete_collection_image', 'collection_thumbs',
+  // The side panel's gallery (lib/gallery.js): images named by job id and number, never by a path.
+  'gallery_list', 'gallery_thumb', 'reveal_image', 'collection_add_job_image',
+]);
+// Windows device names; "CON.txt" or "con .x" open the device too.
+const RESERVED = /^(con|prn|aux|nul|com[0-9¹²³]|lpt[0-9¹²³]|conin\$|conout\$|clock\$)(?=\s*(\.|$))/i;
+
+const chars = s => Array.from(String(s)); // code points, so an emoji is never cut in half
+const cut = (s, n) => chars(s).slice(0, n).join('');
+const tidyName = s => String(s ?? '').replace(/\s/g, ' ').replace(/[\u0000-\u001f\u007f-\u009f]/g, '').replace(/ +/g, ' ').trim();
+const stripEnds = s => s.replace(/^[\s.]+|[\s.]+$/g, '');
+
+// A collection name: 1-64 visible characters once control characters and extra spaces are gone.
+function validateName(name) {
+  const clean = tidyName(name);
+  const n = chars(clean).length;
+  if (!n) return { error: 'The collection name is empty.' };
+  if (n > MAX_NAME) return { error: `The collection name is longer than ${MAX_NAME} characters.` };
+  return { name: clean };
+}
+
+// The folder a collection gets. It never holds a path separator, never starts or ends with a dot or
+// space and is never a device name, so it always stays a plain folder inside the collections folder.
+function safeFolderName(name) {
+  let s = stripEnds(cut(stripEnds(tidyName(String(name ?? '').replace(/[<>:"/\\|?*]/g, ''))), MAX_NAME));
+  if (RESERVED.test(s)) s = stripEnds(cut(s.replace(RESERVED, '$1_'), MAX_NAME));
+  return s || 'collection';
+}
+
+// A bare file name as the host writes them (no folder part, no device name, nothing Windows refuses).
+function isPlainFile(f) {
+  return typeof f === 'string' && /^[^<>:"/\\|?*\u0000-\u001f]{1,200}$/.test(f) && !/^\.+$/.test(f) && !/[ .]$/.test(f) && !RESERVED.test(f);
+}
+
+function isInside(root, p) {
+  const rel = path.relative(path.resolve(root), path.resolve(p));
+  return rel !== '' && !path.isAbsolute(rel) && rel.split(/[\\/]/)[0] !== '..';
+}
+
+// Exact name first, then ignoring case, then (loose) the normalized name used for ChatGPT projects.
+// Returns { collection } or { error: 'NOT_FOUND' | 'AMBIGUOUS', ties }.
+function findCollection(list, name, { loose = true } = {}) {
+  const wanted = tidyName(name);
+  const steps = [c => c.name === wanted, c => c.name.toLowerCase() === wanted.toLowerCase()];
+  if (loose && normName(wanted)) steps.push(c => normName(c.name) === normName(wanted));
+  for (const step of steps) {
+    const hits = list.filter(step);
+    if (hits.length === 1) return { collection: hits[0] };
+    if (hits.length > 1) return { error: 'AMBIGUOUS', ties: hits };
+  }
+  return { error: 'NOT_FOUND' };
+}
+
+// Ties (the same or no addedAt, e.g. a hand-edited manifest) go by the file number, which grows with
+// every image added, so sorting a sorted list again never changes it.
+function newestFirst(images) {
+  const num = im => parseInt(im.file, 10) || 0;
+  return images.slice().sort((a, b) => String(b.addedAt || '').localeCompare(String(a.addedAt || '')) || num(b) - num(a) ||
+    String(b.file).localeCompare(String(a.file)));
+}
+
+const fileOf = f => String(f).split(/[\\/]/).pop().trim(); // a path works as its file name
+
+// The images a job attaches: the files the caller picked (in that order), else the newest ones.
+// unknown lists picked names the collection doesn't have.
+function pickRefs(images, max, chosenFiles) {
+  const room = Math.max(0, max);
+  const picked = (chosenFiles || []).map(fileOf).filter(Boolean);
+  if (!picked.length) return { used: newestFirst(images).slice(0, room), unknown: [] };
+  const byName = new Map(images.map(im => [im.file.toLowerCase(), im]));
+  return {
+    used: [...new Set(picked.map(f => byName.get(f.toLowerCase())).filter(Boolean))].slice(0, room),
+    unknown: picked.filter(f => !byName.has(f.toLowerCase())),
+  };
+}
+
+const mb = n => `${n / 1048576} MB`;
+const refBytes = r => String((r && r.data) || '').length * 0.75; // base64, measured like the host's createJob
+const refError = message => Object.assign(new Error(message), { code: 'BAD_REQUEST' });
+
+// generate with reference_collection: the request with the collection's images after the caller's own
+// references, and what was used (job.collection). find(name) gives the collection (store.find) and
+// read(col, im) one image as a reference ({ name, mime, data }); both throw. The newest images fill the
+// free slots: one that is too large or can't be read is left out for the next one, and adding stops
+// before the references together pass the total limit. Images picked with reference_files are all
+// attached, or the request is refused.
+function withCollection(p, { find, read }, limits = {}) {
+  const { max = MAX_REFS, maxBytes = MAX_REF_BYTES, maxTotal = MAX_REFS_TOTAL_BYTES } = limits;
+  const files = [].concat(p.referenceFiles ?? []).map(fileOf).filter(Boolean);
+  if (!p.referenceCollection) {
+    if (files.length) throw refError('reference_files needs reference_collection.');
+    return { params: p, collection: null };
+  }
+  let col;
+  try { col = find(String(p.referenceCollection)); } catch (e) { throw refError(e.message); }
+  const own = Array.isArray(p.references) ? p.references : [];
+  const room = max - own.length;
+  if (room < 1) throw refError(`reference_images already use all ${max} reference slots, so no collection image fits.`);
+  let budget = maxTotal - own.reduce((sum, r) => sum + refBytes(r), 0);
+  if (budget <= 0) throw refError(`reference_images together already reach ${mb(maxTotal)}, so no collection image fits.`);
+  const { used: wanted, unknown } = pickRefs(col.images, Infinity, files);
+  if (unknown.length) {
+    throw refError(`Collection "${col.name}" has no ${unknown.map(f => `"${f}"`).join(', ')}. ` +
+      `Its files (newest first): ${col.images.slice(0, 40).map(im => im.file).join(', ') || '(none)'}`);
+  }
+  if (!col.images.length) throw refError(`Collection "${col.name}" has no images yet.`);
+  const picked = files.length > 0;
+  if (picked && wanted.length > room) throw refError(`reference_files picks ${wanted.length} images, but only ${room} fit (${max} references per request).`);
+  const refs = [];
+  const used = [];
+  const skipped = [];
+  for (const im of wanted) {
+    if (refs.length >= room) break;
+    let ref;
+    try { ref = read(col, im); } catch (e) {
+      if (picked) throw refError(e.message);
+      skipped.push(`${im.file} (cannot be read)`);
+      continue;
+    }
+    const size = refBytes(ref);
+    if (size > maxBytes) {
+      if (picked) throw refError(`"${im.file}" in collection "${col.name}" is larger than ${mb(maxBytes)}, the most one reference may be.`);
+      skipped.push(`${im.file} (larger than ${mb(maxBytes)})`);
+      continue;
+    }
+    if (size > budget) {
+      if (picked) throw refError(`The picked images and reference_images together are larger than ${mb(maxTotal)}; pick fewer.`);
+      skipped.push(`${im.file} (all references together would pass ${mb(maxTotal)})`);
+      break;
+    }
+    budget -= size;
+    refs.push(ref);
+    used.push(im.file);
+  }
+  if (!refs.length) throw refError(`No image of collection "${col.name}" can be attached: ${skipped.join(', ')}.`);
+  return { params: { ...p, references: [...own, ...refs] }, collection: { name: col.name, used, total: col.count, skipped } };
+}
+
+// NNN_<slug of the source file name>.<ext>; nothing of it is taken from the request as is. name (the
+// host's own, e.g. a generated image's file name) is used instead of the source URL's when given.
+function fileNameFor(index, srcUrl, ext, name = '') {
+  let base = String(name || '');
+  try {
+    const u = new URL(String(srcUrl));
+    if (!base && /^https?:$/.test(u.protocol)) base = decodeURIComponent(u.pathname.split('/').pop() || '');
+  } catch {}
+  base = base.replace(/\.[a-z0-9]{1,5}$/i, '');
+  return `${String(index).padStart(3, '0')}_${slugify(base)}.${IMAGE_EXTS.includes(ext) ? ext : 'png'}`;
+}
+
+function siteOf(url) {
+  try {
+    const u = new URL(String(url));
+    return /^https?:$/.test(u.protocol) ? u.hostname.replace(/^www\./, '') : u.protocol.replace(':', '');
+  } catch { return null; }
+}
+
+// The list_collections tool text.
+function describeCollections(list, maxRefs, maxFiles = 100) {
+  if (!list.length) {
+    return 'No reference collections yet. The user makes them in Chrome: right-click an image, "Add to Backdraw", "New collection…".';
+  }
+  const lines = [`Reference collections (${list.length}, most recently changed first):`];
+  for (const c of list) {
+    lines.push(`- "${c.name}": ${c.count} image(s), folder ${c.path}`);
+    for (const im of c.images.slice(0, maxFiles)) {
+      const site = siteOf(im.pageUrl) || siteOf(im.sourceUrl) || 'unknown source';
+      lines.push(`  - ${im.file} (${site}${im.width ? `, ${im.width}x${im.height}` : ''}, added ${String(im.addedAt || '').slice(0, 10) || '?'})`);
+    }
+    if (c.images.length > maxFiles) lines.push(`  - … ${c.images.length - maxFiles} more in the folder`);
+  }
+  lines.push(`Use one with generate_image(reference_collection="<name>"): its newest images are attached after any reference_images, up to ${maxRefs} references in total. ` +
+    'Pass reference_files=[file names above] to pick specific images instead.');
+  return lines.join('\n');
+}
+
+module.exports = {
+  MAX_NAME, IMAGE_EXTS, EXTENSION_METHODS, chars, cut, validateName, safeFolderName, isPlainFile, isInside,
+  findCollection, newestFirst, pickRefs, withCollection, fileNameFor, siteOf, describeCollections,
+};

package/lib/doctor.js

@@ -0,0 +1,143 @@
+'use strict';
+// `backdraw doctor`: turns the facts doctor.js gathered into checks (✓ / ⚠ / ✗, each with a one-line
+// fix) and prints them so the output can be pasted into an issue: the home folder, which holds the
+// user name, is shown as "~", and project names, prompts and chat links are never printed.
+const path = require('path');
+const { policyProblem } = require('./browsers');
+const { painter, line } = require('./term');
+
+const SETUP = 'npx backdraw@latest setup';
+const FIX = 'npx backdraw@latest doctor --fix';
+
+// Compares "2.1.0"-style versions: > 0 when a is newer.
+function compareVersions(a, b) {
+  const pa = String(a).split('.').map(Number);
+  const pb = String(b).split('.').map(Number);
+  for (let i = 0; i < 3; i++) if ((pa[i] || 0) !== (pb[i] || 0)) return (pa[i] || 0) - (pb[i] || 0);
+  return 0;
+}
+
+const samePath = (a, b) => !!a && !!b && path.resolve(a).toLowerCase() === path.resolve(b).toLowerCase();
+
+// facts: see gather() in doctor.js. Returns [{ status, label, detail, fix, fixable }].
+function evaluate(f) {
+  const checks = [];
+  const add = (status, label, detail, fix = '', fixable = false) => checks.push({ status, label, detail, fix, fixable });
+
+  const major = Number((/^v?(\d+)/.exec(f.node) || [])[1]);
+  if (major >= 20) add('ok', 'Node.js', f.node);
+  else add('fail', 'Node.js', `${f.node} is too old`, 'Install Node.js 20 or newer (nodejs.org).');
+
+  const inst = f.install;
+  if (!inst.exists) add('fail', 'Install folder', `${inst.dir} is missing`, `Run: ${SETUP}`);
+  else if (inst.missing.length) add('fail', 'Install folder', `${inst.dir} lacks ${inst.missing.join(', ')}`, `Run: ${SETUP}`);
+  else add('ok', 'Install folder', `${inst.dir} (${inst.version})`);
+
+  if (inst.exists && inst.version) {
+    if (inst.extensionVersion && inst.extensionVersion !== inst.version) {
+      add('fail', 'Version', `program ${inst.version}, extension files ${inst.extensionVersion}`, `Run: ${SETUP}`);
+    } else if (compareVersions(f.self.version, inst.version) > 0) {
+      add('warn', 'Version', `${inst.version} is installed; this is ${f.self.version}`, `Update: ${SETUP}`);
+    } else {
+      add('ok', 'Version', inst.version);
+    }
+  }
+
+  const hm = f.hostManifest;
+  if (inst.exists) {
+    if (!hm.exists) add('fail', 'Host manifest', 'missing', FIX, true);
+    else if (hm.problem) add('fail', 'Host manifest', hm.problem, FIX, true);
+    else add('ok', 'Host manifest', hm.file);
+  }
+
+  // target: a browser Backdraw registers for (Chrome always, the others when installed).
+  if (f.registryError) add('warn', 'Browsers', `couldn't read the registry (${f.registryError})`);
+  for (const b of f.registryError ? [] : f.browsers.filter(x => x.target)) {
+    const reg = b.registration;
+    if (!reg) add(b.id === 'chrome' ? 'fail' : 'warn', b.name, 'the native host is not registered', FIX, inst.exists);
+    else if (!samePath(reg.path, hm.file)) add('fail', b.name, `the native host points to ${reg.path}`, FIX, inst.exists);
+    else add('ok', b.name, `native host registered (${reg.key} key)`);
+    const blocked = policyProblem(b.policies, f.hostName);
+    if (blocked) add('fail', `${b.name} policy`, blocked, `Backdraw can't run in ${b.name} until an administrator allows it.`);
+  }
+
+  const br = f.bridge;
+  if (!br.ok) {
+    add('fail', 'Bridge', br.code === 'NOT_RUNNING' ? 'not running: the browser is closed, or the extension is not loaded or turned on' : br.error,
+      `Open Chrome. Not loaded yet? Run ${SETUP}; turned off? Turn Backdraw on at chrome://extensions.`);
+  } else {
+    add('ok', 'Bridge', `host ${br.status.hostVersion} answers on the named pipe`);
+  }
+
+  if (br.ok) {
+    const ext = br.status.extension;
+    if (!ext) add('fail', 'Extension', 'not connected', 'Turn Backdraw on at chrome://extensions, or reload it there.');
+    else if (inst.version && ext.version !== inst.version) add('warn', 'Extension', `${ext.version} is running; the files are ${inst.version}`, 'Reload Backdraw at chrome://extensions.');
+    else add('ok', 'Extension', `${ext.version} connected`);
+
+    const chat = f.chatgpt || {};
+    if (chat.error) add('warn', 'ChatGPT', `couldn't ask the extension (${chat.error})`, 'Click the Backdraw icon in Chrome to see the sign-in state.');
+    else if (chat.challenge) add('fail', 'ChatGPT', 'shows a human verification page', 'Open chatgpt.com in Chrome and complete it yourself.');
+    else if (chat.loggedIn === false) add('fail', 'ChatGPT', 'signed out', 'Sign in at chatgpt.com in Chrome.');
+    else if (chat.loggedIn === true) add('ok', 'ChatGPT', 'signed in');
+    else add('warn', 'ChatGPT', 'not checked yet', 'Click the Backdraw icon in Chrome and press "Check now".');
+
+    if (br.status.project) add('ok', 'Project', 'a ChatGPT Project is selected');
+    else add('fail', 'Project', 'no ChatGPT Project is selected', 'Click the Backdraw icon in Chrome and choose a Project.');
+  } else {
+    for (const label of ['Extension', 'ChatGPT', 'Project']) add('info', label, 'not checked (the bridge is not running)');
+  }
+
+  for (const c of f.clients) {
+    if (c.error) add('warn', c.label, c.error);
+    else if (c.entry && c.problem) add('fail', c.label, c.problem, FIX, true);
+    else if (c.entry) add('ok', c.label, 'set up for this install');
+    else if (c.detected) add('warn', c.label, 'Backdraw is not added', `Run: ${SETUP} --clients=${c.id}`);
+  }
+
+  const d = f.desktop;
+  for (const file of d.files) {
+    // The Store (MSIX) app keeps its own copy of the config next to the classic one.
+    const label = d.files.length > 1 ? `Claude desktop (${/\\Packages\\/i.test(file.file) ? 'Store' : 'classic'})` : 'Claude desktop app';
+    if (file.error) add('warn', label, file.error);
+    else if (file.entry && file.problem) {
+      add('fail', label, file.problem, d.running === false ? FIX : `Quit Claude completely (also from the system tray), then run: ${FIX}`, d.running === false);
+    } else if (file.entry) add('ok', label, 'set up for this install');
+    else add('warn', label, 'Backdraw is not added', `Quit Claude completely (also from the system tray), then run: ${SETUP} --clients=claude-desktop`);
+  }
+  if (d.files.length && d.running) add('info', 'Claude desktop app', 'running (Backdraw only changes its config while it is closed)');
+
+  return checks;
+}
+
+// The user's home folder (in the forms it is printed in) as "~", and the pipe's user tag.
+function mask(text, home, userTag) {
+  let out = String(text);
+  if (home) {
+    const forms = new Set([home, home.replace(/\\/g, '/'), home.replace(/\\/g, '\\\\')]);
+    for (const form of [...forms].sort((a, b) => b.length - a.length)) {
+      out = out.replace(new RegExp(form.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'), 'gi'), '~');
+    }
+  }
+  if (userTag) out = out.split(`backdraw-${userTag}`).join('backdraw-~');
+  return out;
+}
+
+function format(checks, { header, color = false } = {}) {
+  const paint = painter(color);
+  const width = Math.max(...checks.map(c => c.label.length));
+  const lines = header ? [header, ''] : [];
+  for (const c of checks) {
+    lines.push(line(paint, c.status, c.label, c.detail, width));
+    if (c.fix) lines.push(`  ${' '.repeat(width)} → ${c.fix}`);
+  }
+  const fails = checks.filter(c => c.status === 'fail').length;
+  const warns = checks.filter(c => c.status === 'warn').length;
+  const fixable = checks.filter(c => c.fixable).length;
+  lines.push('', fails || warns
+    ? `${fails} problem${fails === 1 ? '' : 's'}, ${warns} warning${warns === 1 ? '' : 's'}.${fixable ? ` "${FIX}" can repair ${fixable} of them.` : ''}`
+    : 'Everything looks good.');
+  return lines.join('\n');
+}
+
+module.exports = { compareVersions, evaluate, mask, format, SETUP, FIX };