@scrymore/scry-deployer 0.11.1 → 0.12.0-next.20261003113319

package/README.md

@@ -97,6 +97,8 @@ This deploys your Storybook immediately without setting up GitHub Actions.
 
 **You don't need to install anything!** Just use `npx` to run the init command:
 
+Requires Node.js 20.9 or newer (Node 18 is end of life; use `@scrymore/scry-deployer@0.11` if you are stuck on it).
+
 ```bash
 # From npm (recommended)
 npx @scrymore/scry-deployer init --projectId xxx --apiKey yyy
@@ -787,7 +789,7 @@ See the complete workflow configuration: [`.github/workflows/deploy-pr-preview.y
 Key workflow features:
 - **Triggers**: `pull_request` with types `[opened, synchronize, reopened]`
 - **Permissions**: `contents: read`, `pull-requests: write`
-- **Node version**: 18 (configurable in workflow)
+- **Node version**: 20 (configurable in workflow)
 - **Comment management**: Smart update/create logic to avoid duplicate comments
 
 #### Cleanup

package/lib/converter/bundle.js

@@ -0,0 +1,298 @@
+/**
+ * buildBundle(...): converted files -> one SCF 1.0 bundle (`scf.json` + `images/`) for Scry Sync.
+ *
+ * What goes in (guarantee G2: no originals, no paths):
+ *   - only the converted pictures (sRGB PNG/JPEG, <= 2048 px, <= 4 MB), never an original file;
+ *   - ids from pictureId(folderUuid, relativePath[, page]) (a hash: no path or name can be read back);
+ *   - image files named by the hash of the id, so no file name reaches the bundle as a path;
+ *   - title = [folder label, file name without extension] (founder decision D2), `name` "Page N" for pages;
+ *   - the `x-scry-sync` block: the allow-listed XMP fields (title, description, keywords, rating, label), each one
+ *     kept UNCHANGED or DROPPED ENTIRELY by the structural rule in privacy.js (anything that carries a path
+ *     separator, a drive, `file:`, the folder's location or the user's name is dropped, never edited), plus `origin`
+ *     ({convertedFrom, verdict, appVersion} and nothing else) and, when a value was dropped, `notes`
+ *     ([{code: 'metadata_dropped', fields: [field names]}], never the value; also on the file's result row), and
+ *     when a kept field was cut to its XMP cap, {code: 'metadata_truncated', fields: [field names]}.
+ *     `creator` is not read from XMP today; if a source ever supplies one it goes through the same rule.
+ *   - the title's file part is the file name without its extension, as the user named it, when it passes the same
+ *     rule as the XMP values (F157); a name that carries a location (a Mac colon path, a slash lookalike, the user's
+ *     name) loses the offending words, or becomes `Untitled <6 hex>`, and `fileName` joins the `metadata_dropped`
+ *     note; a file whose name holds a backslash or a control character is not captured (failed verdict `odd_name`).
+ * Every file that is not captured is counted in `counts.skipped` with its plain-language reason (G3).
+ * A bundle over 1 GiB (the server's limit) or over 10,000 captures (the SCF limit) is refused before upload.
+ */
+const crypto = require('crypto');
+const fs = require('fs');
+const path = require('path');
+const { SCF_SCHEMA_URL } = require('../scf.js');
+const { pictureId } = require('./ids.js');
+const { convertFile } = require('./convert.js');
+const { SKIP_REASON, FAILED, failed } = require('./verdicts.js');
+const { makeLeakCheck, keepIfClean } = require('./privacy.js');
+
+const SOURCE_KIND = 'x-scry-sync';
+const VENDOR_KEY = 'x-scry-sync';
+const MAX_BUNDLE_BYTES = 1024 * 1024 * 1024;
+/** The SCF validator's per-bundle capture cap (BUNDLE_TOO_MANY_CAPTURES). */
+const MAX_BUNDLE_CAPTURES = 10_000;
+const TOO_MANY_MESSAGE = 'This folder would make more than 10,000 pictures, which is over the limit; link a smaller folder';
+const TOO_BIG_MESSAGE = 'This folder is too big; link a smaller folder';
+const CONVERTED_FROM = new Set(['png', 'jpeg', 'webp', 'heic', 'heif', 'tiff', 'psd', 'psb', 'pdf', 'ai']);
+const APP_VERSION_RE = /^\d{1,4}\.\d{1,4}\.\d{1,6}(?:-[0-9A-Za-z.]{1,32})?$/;
+const EXT_OF_FAMILY = { png: 'png', jpeg: 'jpg', webp: 'webp' };
+
+class BundleTooBigError extends Error {
+    constructor() {
+        super(TOO_BIG_MESSAGE);
+        this.name = 'BundleTooBigError';
+        this.code = 'bundle_too_big';
+    }
+}
+
+class TooManyCapturesError extends Error {
+    constructor() {
+        super(TOO_MANY_MESSAGE);
+        this.name = 'TooManyCapturesError';
+        this.code = 'too_many_captures';
+    }
+}
+
+/** The `origin` block: which format a picture came from, its verdict and the app version. Nothing else. */
+function originBlock({ format, verdict, appVersion }) {
+    const origin = {};
+    if (CONVERTED_FROM.has(format)) origin.convertedFrom = format;
+    if (verdict === 'faithful' || verdict === 'approximate') origin.verdict = verdict;
+    if (typeof appVersion === 'string' && APP_VERSION_RE.test(appVersion)) origin.appVersion = appVersion;
+    return origin;
+}
+
+/** A name that cannot be a file name on every OS, or that would read as a path: it is refused, not rewritten. */
+function oddFileName(rel) {
+    if (typeof rel !== 'string' || rel.length === 0 || rel.includes('\\')) return true;
+    for (let i = 0; i < rel.length; i += 1) {
+        const code = rel.charCodeAt(i);
+        if (code < 0x20 || code === 0x7f) return true;
+    }
+    return false;
+}
+
+/**
+ * The allow-listed XMP text fields, each unchanged or dropped by the structural rule (privacy.js); a keyword list
+ * keeps the keywords that pass and drops the others one by one. Returns the kept fields and the NAMES of the fields
+ * that lost a value (never the values), for the `metadata_dropped` note.
+ */
+function cleanMeta(xmp, leaks) {
+    const meta = {};
+    const dropped = [];
+    for (const key of ['title', 'description', 'label', 'creator']) {
+        if (typeof xmp[key] !== 'string' || xmp[key].length === 0) continue;
+        const value = keepIfClean(xmp[key], leaks);
+        if (value) meta[key] = value;
+        else dropped.push(key);
+    }
+    if (Array.isArray(xmp.keywords)) {
+        const keywords = xmp.keywords.map((k) => keepIfClean(k, leaks)).filter(Boolean);
+        if (keywords.length) meta.keywords = keywords;
+        if (keywords.length < xmp.keywords.filter((k) => typeof k === 'string' && k.length > 0).length) dropped.push('keywords');
+    }
+    if (Number.isInteger(xmp.rating)) meta.rating = xmp.rating;
+    return { meta, dropped };
+}
+
+/**
+ * The note that tells the person why a title, keyword or label vanished (F76): the code and the field names only.
+ * `folderLabel` is listed when the folder's label was dropped (the title is then the file name alone).
+ */
+function metadataNotes(dropped, truncated = []) {
+    const notes = [];
+    if (dropped.length) notes.push({ code: 'metadata_dropped', fields: dropped });
+    if (truncated.length) notes.push({ code: 'metadata_truncated', fields: truncated });
+    return notes.length ? notes : null;
+}
+
+const MAX_LABEL_LENGTH = 200;
+
+/**
+ * A folder label is a display name: cut to its shown length FIRST (so a long label is never scanned whole, F109), then
+ * unchanged when it carries no location, otherwise dropped (the title is then the file name alone).
+ */
+function cleanLabel(label, leaks) {
+    if (typeof label !== 'string') return '';
+    return keepIfClean(Array.from(label).slice(0, MAX_LABEL_LENGTH).join(''), leaks) || '';
+}
+
+function stemOf(rel) {
+    const base = rel.split('/').pop();
+    const dot = base.lastIndexOf('.');
+    return dot > 0 ? base.slice(0, dot) : base;
+}
+
+function sha256Hex(text) {
+    return crypto.createHash('sha256').update(text).digest('hex');
+}
+
+/**
+ * The title's file part, run through the same rule as every other free-text value (F157: a file named
+ * `Users:<user>:Desktop` (macOS shows `/` as `:`) or `\u2215home\u2215<user>\u2215x` is a path in disguise).
+ *   - clean: the stem, exactly as the user named it;
+ *   - otherwise the stem without its offending words (split on spaces; every word that carries a location is left
+ *     out and the rest is checked again as a whole, so a location spread over several words cannot survive);
+ *   - otherwise `Untitled <6 hex of the picture id>` (a hash: the same file keeps the same title, two files differ).
+ * The file is captured either way. Returns the title part and whether the name was changed (noted as `fileName`).
+ */
+function safeStem(rel, leaks, id) {
+    const stem = stemOf(rel) || 'Untitled';
+    if (!leaks(stem)) return { stem, changed: false };
+    const rest = stem.split(/\s+/).filter((word) => word && !leaks(word)).join(' ');
+    if (rest && !leaks(rest)) return { stem: rest, changed: true };
+    return { stem: `Untitled ${String(id).slice(0, 6)}`, changed: true };
+}
+
+/**
+ * @param {object} args
+ * @param {string} args.folderUuid the synced folder's UUID (ids)
+ * @param {{root:string, files:Array<{abs:string, rel:string}>, refused?:Array}} args.scan scanFolder() result
+ * @param {string} args.outDir an empty directory to write the bundle into
+ * @param {string} args.appVersion the app version, for `origin` and `source.tool`
+ * @param {string} [args.folderLabel] display name of the folder (first title segment)
+ * @param {object} [args.convertOptions] passed to convertFile (decoders, tools)
+ * @param {Function} [args.convert] convertFile replacement (tests)
+ * @param {number} [args.maxBundleBytes] defaults to 1 GiB
+ * @param {Date} [args.now]
+ * @returns {Promise<{manifest:object, results:Array<{rel:string, verdict:string, codes:string[], reasons:string[], fix:string|null, ids:string[], notes?:Array<{code:'metadata_dropped'|'metadata_truncated', fields:string[]}>}>, bytes:number}>}
+ * @throws {BundleTooBigError} "This folder is too big; link a smaller folder"
+ */
+async function buildBundle(args) {
+    const { scan, outDir, appVersion } = args;
+    const leaks = makeLeakCheck({ root: scan.root });
+    const label = cleanLabel(args.folderLabel, leaks);
+    const state = {
+        args,
+        leaks,
+        label,
+        labelDropped: typeof args.folderLabel === 'string' && args.folderLabel.length > 0 && label === '',
+        maxBytes: args.maxBundleBytes || MAX_BUNDLE_BYTES,
+        captures: [],
+        skipped: [],
+        results: [],
+        bytes: 0,
+    };
+    fs.mkdirSync(path.join(outDir, 'images'), { recursive: true });
+    for (const refused of scan.refused || []) {
+        skipFile(state, refused);
+        state.results.push({ rel: refused.rel, verdict: 'failed', codes: refused.codes, reasons: refused.reasons, fix: refused.fix, ids: [] });
+    }
+    try {
+        for (const file of scan.files) await addFile(state, file);
+        const manifest = {
+            $schema: SCF_SCHEMA_URL,
+            scf: '1.0',
+            source: { kind: SOURCE_KIND, platform: 'other', tool: { name: 'scry-sync', version: APP_VERSION_RE.test(String(appVersion)) ? appVersion : 'unknown' } },
+            createdAt: (args.now || new Date()).toISOString(),
+            counts: { declared: scan.files.length + (scan.refused || []).length, captured: state.captures.length, skipped: state.skipped },
+            captures: state.captures,
+        };
+        const json = JSON.stringify(manifest, null, 2) + '\n';
+        countBytes(state, Buffer.byteLength(json));
+        fs.writeFileSync(path.join(outDir, 'scf.json'), json);
+        return { manifest, results: state.results, bytes: state.bytes };
+    } catch (error) {
+        if (error instanceof BundleTooBigError || error instanceof TooManyCapturesError) fs.rmSync(path.join(outDir, 'images'), { recursive: true, force: true });
+        throw error;
+    }
+}
+
+function countBytes(state, n) {
+    state.bytes += n;
+    if (state.bytes > state.maxBytes) throw new BundleTooBigError();
+}
+
+/**
+ * A failed file goes into counts.skipped with its plain reason. The reasons are our own sentences; if one ever
+ * carried a location (a tool's message, say) it is replaced by the code's standard sentence, never edited.
+ */
+function skipFile(state, result) {
+    const code = result.codes[0];
+    const text = result.reasons.join(' ');
+    const standard = FAILED[code] ? FAILED[code][0] : 'The file could not be converted.';
+    const detail = state.leaks(text) ? standard : text;
+    state.skipped.push({ id: `file-${state.skipped.length + 1}`, reason: SKIP_REASON[code] || 'error', detail });
+}
+
+/** The id of every picture of a converted file, or null when the file's name cannot be an id (checked before anything is written). */
+function idsFor(state, file, pictures) {
+    try {
+        return pictures.map((picture) => pictureId(state.args.folderUuid, file.rel, picture.suffix ? Number(picture.suffix.slice(2)) : undefined));
+    } catch {
+        return null;
+    }
+}
+
+/** The `x-scry-sync` block of a converted file; a `metadata_dropped` note also goes on the file's result row. */
+function vendorBlock(state, result, entry, fileNameChanged) {
+    const { meta, dropped: droppedMeta } = cleanMeta(result.xmp || {}, state.leaks);
+    const dropped = fileNameChanged ? [...droppedMeta, 'fileName'] : droppedMeta;
+    // F122: a kept field that importXmp cut to its cap (title 200, description 2000, ...) is named, never its value.
+    const truncated = (result.xmpTruncated || []).filter((field) => field in meta);
+    const notes = metadataNotes(state.labelDropped ? [...dropped, 'folderLabel'] : dropped, truncated);
+    const block = { ...meta, origin: originBlock({ format: result.format, verdict: result.verdict, appVersion: state.args.appVersion }) };
+    if (notes) {
+        block.notes = notes;
+        entry.notes = notes;
+    }
+    return { meta, block };
+}
+
+/** Convert one file and add a capture per picture (or a skip). */
+async function addFile(state, file) {
+    const { args } = state;
+    let result;
+    try {
+        result = oddFileName(file.rel) ? failed(null, 'odd_name') : await (args.convert || convertFile)(file.abs, { ...(args.convertOptions || {}), root: args.scan.root });
+    } catch {
+        result = failed(null, 'unreadable');
+    }
+    const ids = result.verdict === 'failed' ? [] : idsFor(state, file, result.pictures);
+    if (!ids) result = failed(null, 'odd_name');
+    const entry = { rel: file.rel, verdict: result.verdict, codes: result.codes, reasons: result.reasons, fix: result.fix, ids: [] };
+    state.results.push(entry);
+    if (result.verdict === 'failed') {
+        skipFile(state, result);
+        return;
+    }
+    const { stem, changed } = safeStem(file.rel, state.leaks, ids[0]);
+    const { meta, block } = vendorBlock(state, result, entry, changed);
+    const title = state.label ? [state.label, stem] : [stem];
+    for (const [index, picture] of result.pictures.entries()) {
+        if (state.captures.length >= MAX_BUNDLE_CAPTURES) throw new TooManyCapturesError();
+        const page = picture.suffix ? Number(picture.suffix.slice(2)) : undefined;
+        const id = ids[index];
+        const name = `${sha256Hex(id)}.${EXT_OF_FAMILY[picture.family]}`;
+        countBytes(state, picture.bytes.length);
+        fs.writeFileSync(path.join(args.outDir, 'images', name), picture.bytes);
+        const capture = {
+            id,
+            image: `images/${name}`,
+            kind: 'doc-image',
+            title,
+            capture: { method: 'design-export', size: { width: picture.width, height: picture.height } },
+            [VENDOR_KEY]: block,
+        };
+        if (page) capture.name = `Page ${page}`;
+        if (meta.keywords) capture.tags = meta.keywords;
+        state.captures.push(capture);
+        entry.ids.push(id);
+    }
+}
+
+module.exports = {
+    SOURCE_KIND,
+    VENDOR_KEY,
+    MAX_BUNDLE_BYTES,
+    MAX_BUNDLE_CAPTURES,
+    TOO_BIG_MESSAGE,
+    TOO_MANY_MESSAGE,
+    BundleTooBigError,
+    TooManyCapturesError,
+    originBlock,
+    buildBundle,
+};

package/lib/converter/convert.js

@@ -0,0 +1,239 @@
+/**
+ * convertFile(path, opts): one file in the synced folder -> its pictures and an honest verdict (guarantee G3).
+ *
+ *   { format, pictures: [{ suffix, bytes, family, width, height }], verdict, codes, reasons, fix }
+ *
+ * `suffix` is '' for a single picture and `#p<N>` for each PDF/AI page (always, even a one-page PDF, so adding a
+ * page later never changes the first page's id). Pictures are sRGB PNG/JPEG, <= 2048 px, <= 4 MB, no metadata.
+ * The verdict is `faithful`, `approximate` (with reasons) or `failed` (no pictures, a reason and the fix).
+ * convertFile never throws for a bad file: whatever happens, the file gets a verdict.
+ */
+const fs = require('fs');
+const path = require('path');
+const { measure } = require('../importConvert.js');
+const legacy = require('../importConvert.js');
+const { stripMetadata } = require('../importStrip.js');
+const { readEmbeddedPacket, parseAllowListed, mergeXmp } = require('../importXmp.js');
+const { readSidecarPacket } = require('../importScan.js');
+const { sharp, tooLarge, isSrgbProfile, encodeForScry, readOptions, MAX_RASTER_BYTES, MAX_RASTER_DIMENSION } = require('./raster.js');
+const { readPsdComposite } = require('./psd.js');
+const { renderPdfPages, hasPdfHeader } = require('./pdf.js');
+const { failed, finish } = require('./verdicts.js');
+const { openNoFollow, readNoFollow } = require('./safeopen.js');
+const { confinedRealPath } = require('../importScan.js');
+
+/** Extension -> format (the `convertedFrom` value in the origin block). */
+const FORMATS = Object.freeze({
+    '.png': 'png',
+    '.jpg': 'jpeg',
+    '.jpeg': 'jpeg',
+    '.webp': 'webp',
+    '.tif': 'tiff',
+    '.tiff': 'tiff',
+    '.psd': 'psd',
+    '.psb': 'psb',
+    '.pdf': 'pdf',
+    '.ai': 'ai',
+    '.heic': 'heic',
+    '.heif': 'heif',
+    '.indd': 'indd',
+});
+const PASS_THROUGH = new Set(['png', 'jpeg', 'webp']);
+/** Bigger source files are refused before reading (a 200 MP picture is far below this). */
+const MAX_SOURCE_BYTES = 2 * 1024 * 1024 * 1024;
+
+function formatOf(file) {
+    return FORMATS[path.extname(file).toLowerCase()] || null;
+}
+
+async function encodeOne(open) {
+    const out = await encodeForScry(open);
+    return out ? { suffix: '', ...out } : null;
+}
+
+/** PNG/JPEG/WebP/TIFF through sharp; an untouched copy (metadata stripped) when it is already sRGB and in bounds. */
+async function convertRaster(file, format) {
+    const meta = await sharp(file, readOptions()).metadata();
+    if (tooLarge(meta.width, meta.height)) return failed(format, 'too_large', `${meta.width}x${meta.height}`);
+    const codes = [];
+    if ((meta.pages || 1) > 1) codes.push('extra_frames');
+    if (meta.space === 'cmyk' && !meta.icc) codes.push('cmyk_no_icc');
+    if (PASS_THROUGH.has(format) && meta.space !== 'cmyk' && isSrgbProfile(meta.icc) && (meta.orientation || 1) === 1) {
+        const raw = readNoFollow(file);
+        const found = measure(raw);
+        const clean = found ? stripMetadata(raw, found.family) : null;
+        const dims = clean ? measure(clean) : null;
+        const fits = dims && clean.length <= MAX_RASTER_BYTES && dims.width <= MAX_RASTER_DIMENSION && dims.height <= MAX_RASTER_DIMENSION;
+        if (fits && !legacy.outputProblem(clean, dims)) return finish(format, [{ suffix: '', bytes: clean, ...dims }], codes);
+    }
+    const picture = await encodeOne(() => sharp(file, readOptions()).rotate());
+    return picture ? finish(format, [picture], codes) : failed(format, 'output_too_big');
+}
+
+async function convertPsd(file, format) {
+    const composite = readPsdComposite(file);
+    if (composite.failure) return failed(format, composite.failure, composite.failure === 'too_large' ? `${composite.width}x${composite.height}` : undefined);
+    const picture = await encodeOne(() => sharp(composite.tiff));
+    return picture ? finish(format, [picture], composite.codes) : failed(format, 'output_too_big');
+}
+
+class PageTooBig extends Error {
+    constructor(page) {
+        super('page too big');
+        this.page = page;
+    }
+}
+
+async function convertPdf(file, format) {
+    const bytes = readNoFollow(file);
+    if (format === 'ai' && !hasPdfHeader(bytes)) return failed(format, 'ai_no_pdf');
+    const pictures = [];
+    // Each page is encoded and released before the next is drawn (see pdf.js); only the small encoded pictures are kept.
+    let rendered;
+    try {
+        rendered = await renderPdfPages(bytes, async (page) => {
+            const raw = { raw: { width: page.width, height: page.height, channels: 3 } };
+            const picture = await encodeForScry(() => sharp(page.rgb, raw));
+            if (!picture) throw new PageTooBig(page.page);
+            pictures.push({ suffix: `#p${page.page}`, ...picture });
+        });
+    } catch (error) {
+        if (error instanceof PageTooBig) return failed(format, 'output_too_big', `page ${error.page}`);
+        throw error;
+    }
+    if (rendered.failure) return failed(format, rendered.failure);
+    return finish(format, pictures, rendered.codes);
+}
+
+/**
+ * HEIC/HEIF. The decoder is the OS's, plugged in by the app (`opts.decoders.heic(path) -> Promise<Buffer>` of a
+ * PNG/JPEG/TIFF sharp can read: Windows WIC, macOS ImageIO). Without one, the command-line tools `scry import`
+ * uses (sips, ImageMagick) are tried, whose colours are not converted to sRGB (approximate).
+ */
+async function convertHeic(file, format, opts) {
+    const decode = opts.decoders && opts.decoders.heic;
+    if (decode) {
+        let decoded;
+        try {
+            decoded = await decode(file);
+        } catch {
+            return failed(format, 'unreadable', 'the HEIC decoder could not read it');
+        }
+        const meta = await sharp(decoded, readOptions()).metadata();
+        if (tooLarge(meta.width, meta.height)) return failed(format, 'too_large', `${meta.width}x${meta.height}`);
+        const picture = await encodeOne(() => sharp(decoded, readOptions()).rotate());
+        return picture ? finish(format, [picture], []) : failed(format, 'output_too_big');
+    }
+    const tools = opts.tools || legacy.detectTools();
+    if (tools.filter((t) => t !== 'pdftoppm').length === 0) return failed(format, 'heic_no_decoder');
+    const result = await legacy.convertFile(file, '.heic', { tools, run: opts.run });
+    if (!result.ok) return failed(format, 'unreadable', result.detail);
+    const { bytes, family, width, height } = result;
+    return finish(format, [{ suffix: '', bytes, family, width, height }], ['colour_unmanaged']);
+}
+
+/** Allow-listed XMP (title, description, keywords, rating, label, creator) from the file and its .xmp sidecar. */
+function readXmp(file, root) {
+    let embedded = {};
+    const embeddedCut = new Set();
+    const fd = openNoFollow(file);
+    const size = fs.fstatSync(fd).size;
+    try {
+        const packet = readEmbeddedPacket(fd, size);
+        if (packet) embedded = parseAllowListed(packet, { cut: embeddedCut });
+    } finally {
+        fs.closeSync(fd);
+    }
+    const sidecarCut = new Set();
+    const sidecar = root ? readSidecarPacket(file, root) : {};
+    const fromSidecar = sidecar.packet ? parseAllowListed(sidecar.packet, { cut: sidecarCut }) : {};
+    const xmp = mergeXmp(embedded, fromSidecar);
+    // A field was cut when the copy that won the merge (the sidecar's, else the file's) was cut.
+    const cut = Object.keys(xmp).filter((field) => (field in fromSidecar ? sidecarCut : embeddedCut).has(field));
+    return { xmp, cut };
+}
+
+async function dispatch(file, format, opts) {
+    if (format === 'indd') return failed(format, 'indd_needs_pdf');
+    if (format === 'psd' || format === 'psb') return convertPsd(file, format);
+    if (format === 'pdf' || format === 'ai') return convertPdf(file, format);
+    if (format === 'heic' || format === 'heif') return convertHeic(file, format, opts);
+    return convertRaster(file, format);
+}
+
+/** What identifies the file between two looks at it (a swap or an edit changes it). */
+function signatureOf(stat) {
+    return `${stat.dev}:${stat.ino}:${stat.size}:${stat.mtimeMs}`;
+}
+
+/**
+ * The checks made at READ time, not only at scan time (the folder can change between the two): the path is a plain
+ * file (not a link) and its real path is inside the real root (`root` is required: convertFile refuses to run
+ * without it). Returns a failed code or the file's signature.
+ */
+function checkAtRead(file, root) {
+    let stat;
+    try {
+        stat = fs.lstatSync(file);
+    } catch {
+        return { code: 'unreadable' };
+    }
+    if (stat.isSymbolicLink()) return { code: 'not_followed' };
+    if (!stat.isFile()) return { code: 'unreadable' };
+    let realRoot;
+    try {
+        realRoot = fs.realpathSync(root);
+    } catch {
+        return { code: 'outside_folder' };
+    }
+    if (!confinedRealPath(file, realRoot)) return { code: 'outside_folder' };
+    return { stat, signature: signatureOf(stat) };
+}
+
+async function convertChecked(file, format, opts) {
+    const before = checkAtRead(file, opts.root);
+    if (before.code) return failed(format, before.code);
+    if (before.stat.size === 0) return failed(format, 'empty');
+    if (before.stat.size > MAX_SOURCE_BYTES) return failed(format, 'too_large', 'file over 2 GB');
+    const result = await dispatch(file, format, opts);
+    // Looked at again after the read: a file swapped for a link (or edited) while it was read is not trusted.
+    const after = checkAtRead(file, opts.root);
+    if (after.code) return failed(format, after.code);
+    if (after.signature !== before.signature) return failed(format, 'changed_while_reading');
+    return result;
+}
+
+/**
+ * @param {string} file absolute path
+ * @param {{root:string, decoders?:{heic?:(file:string)=>Promise<Buffer>}, tools?:string[], run?:Function, metadata?:boolean}} [opts]
+ *   `root` (required): the synced folder; every read is confined to it (a file or a subfolder swapped for a link to
+ *   somewhere outside fails as `outside_folder`), and the .xmp sidecar is looked up inside it. `metadata: false` skips XMP.
+ * @throws {TypeError} when `root` is missing (the message names the option, never the file)
+ * @returns {Promise<{format:string|null, pictures:Array, verdict:'faithful'|'approximate'|'failed', codes:string[], reasons:string[], fix:string|null, xmp?:object, xmpTruncated?:string[]}>}
+ */
+async function convertFile(file, opts = {}) {
+    if (!opts || typeof opts.root !== 'string' || opts.root.length === 0) {
+        throw new TypeError('convertFile needs opts.root (the synced folder) so that every read stays inside it');
+    }
+    const format = formatOf(file);
+    if (!format) return failed(null, 'unsupported_type');
+    let result;
+    try {
+        result = await convertChecked(file, format, opts);
+    } catch (error) {
+        const tooBig = /pixel limit|exceeds|too large/i.test(String(error && error.message));
+        result = failed(format, tooBig ? 'too_large' : 'unreadable');
+    }
+    if (result.verdict !== 'failed' && opts.metadata !== false) {
+        try {
+            const { xmp, cut } = readXmp(file, opts.root);
+            if (Object.keys(xmp).length > 0) result.xmp = xmp;
+            if (cut.length > 0) result.xmpTruncated = cut;
+        } catch {
+            // metadata is optional; the picture stands without it
+        }
+    }
+    return result;
+}
+
+module.exports = { FORMATS, formatOf, convertFile };

package/lib/converter/ids.js

@@ -0,0 +1,57 @@
+/**
+ * Stable picture ids for Scry Sync (founder decision D2: identify a picture by its place in the folder,
+ * not by its content, so editing a file keeps its id and the Figma links, issues and history on it).
+ *
+ *   pictureId(folderUuid, relativePath)        = sha256(folderUuid + normalisedPath), lower-case hex
+ *   pictureId(folderUuid, relativePath, page)  = the same + `#p<page>` (PDF/AI pages, 1-based)
+ *
+ * Normalisation of the relative path, so the same file gives the same id on Windows and on a Mac:
+ *   - separators: every `\` becomes `/` (a Windows path and a Mac path of the same file are equal);
+ *   - leading `./` and `/`, repeated `/` and `.` segments are removed; `..` is refused (not inside the folder);
+ *   - Unicode NFC (macOS hands out decomposed NFD names, Windows composed NFC ones);
+ *   - case is PRESERVED: `Home.psd` and `home.psd` are two ids (a rename that only changes case is a new id).
+ *
+ * The folder UUID is minted once per synced folder by the app and kept locally; it is a fixed-length UUID, so
+ * plain concatenation is unambiguous. The id is a hash: no path, file name or user name can be read from it.
+ */
+const crypto = require('crypto');
+
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+class PictureIdError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'PictureIdError';
+    }
+}
+
+/** The relative path in the one form every OS agrees on (see the module comment). */
+function normaliseRelativePath(relativePath) {
+    if (typeof relativePath !== 'string' || relativePath.length === 0) throw new PictureIdError('relative path is empty');
+    const segments = relativePath.normalize('NFC').replace(/\\/g, '/').split('/');
+    const kept = [];
+    for (const segment of segments) {
+        if (segment === '' || segment === '.') continue;
+        if (segment === '..') throw new PictureIdError('relative path leaves the folder');
+        kept.push(segment);
+    }
+    if (kept.length === 0) throw new PictureIdError('relative path is empty');
+    if (/^[A-Za-z]:$/.test(kept[0])) throw new PictureIdError('expected a path relative to the synced folder, got a drive path');
+    return kept.join('/');
+}
+
+/**
+ * @param {string} folderUuid the synced folder's UUID
+ * @param {string} relativePath path of the file inside the folder, with `/` or `\`
+ * @param {number} [page] 1-based page for PDF/AI pictures
+ * @returns {string} 64 hex chars, plus `#p<page>` when a page is given
+ */
+function pictureId(folderUuid, relativePath, page) {
+    if (typeof folderUuid !== 'string' || !UUID_RE.test(folderUuid)) throw new PictureIdError('folder id must be a UUID');
+    const hex = crypto.createHash('sha256').update(folderUuid.toLowerCase() + normaliseRelativePath(relativePath), 'utf8').digest('hex');
+    if (page === undefined || page === null) return hex;
+    if (!Number.isInteger(page) || page < 1) throw new PictureIdError('page must be a positive integer');
+    return `${hex}#p${page}`;
+}
+
+module.exports = { PictureIdError, normaliseRelativePath, pictureId };

package/lib/converter/index.js

@@ -0,0 +1,42 @@
+/**
+ * Scry Sync converter: the library the desktop app (scry-sync, Electron main process) uses to turn a synced
+ * folder into an SCF bundle. CommonJS, Node >= 20.9, no network, no child processes unless the HEIC fallback is used.
+ *
+ *   const converter = require('@scrymore/scry-deployer/lib/converter');
+ *   const scan = converter.scanFolder(folder);                         // files with kind and size; refused ones
+ *   const one = await converter.convertFile(file, { root: scan.root, decoders }); // pictures + verdict + reasons + fix (root required)
+ *   const { manifest } = await converter.buildBundle({ folderUuid, scan, outDir, appVersion });
+ *   converter.pictureId(folderUuid, 'Sub/Home.psd')                    // stable id (see ids.js)
+ *
+ * `scry import` (the CLI) is unchanged and does not use this module.
+ */
+const { pictureId, normaliseRelativePath, PictureIdError } = require('./ids.js');
+const { scanFolder, ScanError, kindOf, isTooBroad } = require('./scan.js');
+const { convertFile, FORMATS } = require('./convert.js');
+const { buildBundle, originBlock, BundleTooBigError, TooManyCapturesError, TOO_BIG_MESSAGE, TOO_MANY_MESSAGE, SOURCE_KIND, VENDOR_KEY, MAX_BUNDLE_BYTES, MAX_BUNDLE_CAPTURES } = require('./bundle.js');
+const { VERDICTS, APPROXIMATE, FAILED } = require('./verdicts.js');
+const { MAX_SOURCE_EDGE, MAX_SOURCE_PIXELS, MAX_RASTER_BYTES, MAX_RASTER_DIMENSION } = require('./raster.js');
+
+module.exports = {
+    scanFolder,
+    convertFile,
+    buildBundle,
+    pictureId,
+    normaliseRelativePath,
+    originBlock,
+    kindOf,
+    isTooBroad,
+    FORMATS,
+    VERDICTS,
+    APPROXIMATE,
+    FAILED,
+    SOURCE_KIND,
+    VENDOR_KEY,
+    LIMITS: Object.freeze({ MAX_SOURCE_EDGE, MAX_SOURCE_PIXELS, MAX_RASTER_BYTES, MAX_RASTER_DIMENSION, MAX_BUNDLE_BYTES, MAX_BUNDLE_CAPTURES }),
+    TOO_BIG_MESSAGE,
+    TOO_MANY_MESSAGE,
+    BundleTooBigError,
+    TooManyCapturesError,
+    PictureIdError,
+    ScanError,
+};