fundus 0.0.2 → 0.0.3

package/dist/server/library-store.js

@@ -0,0 +1,763 @@
+/**
+ * The fs-backed store over the library file (SSOT) and the raw directory.
+ * Every mutation is load → modify → deterministic write, so the file on disk
+ * is always the current truth. Proxy files are the pipeline's business — this
+ * store only removes them on asset deletion (the pipeline also prunes orphans).
+ */
+import { existsSync } from 'node:fs';
+import { mkdir, readFile, rename, rm, unlink, writeFile } from 'node:fs/promises';
+import { dirname, extname, join } from 'node:path';
+import { createHash } from 'node:crypto';
+import { assetIdError, collectAllReferences, createEmptyLibrary, folderNameError, folderNameOf, folderOfRawPath, folderPathError, isFolderOrDescendant, joinFolderPath, manifestColorError, manifestEmojiError, parseLibrary, referenceErrors, normalizeFolderPath, parentFolderPath, portableFolderPathKey, rawFileNameOfPath, replaceFolderPrefix, manifestNameError, serializeLibrary } from '../core/index.js';
+import { manifestModuleFileName } from './codegen.js';
+import { descriptorsByType, serverPluginForType, serverPluginsByType } from './plugins.js';
+import { isProxyFileNameFor } from './processing/processor.js';
+import { ensureManagedFolder, listRelativeFiles, syncManagedFolders } from './folder-filesystem.js';
+/** A single path segment with no traversal — guards against `../` escapes. */
+const SAFE_SEGMENT = /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/;
+export function assertSafeFileName(fileName) {
+    if (!SAFE_SEGMENT.test(fileName) || fileName.includes('/') || fileName.includes('\\')) {
+        throw new Error(`Unsafe file name "${fileName}".`);
+    }
+}
+/** Validate a persisted/served file path without allowing traversal outside its root. */
+export function assertSafeRelativeFilePath(filePath) {
+    if (filePath.startsWith('/') || filePath.endsWith('/') || filePath.includes('\\')) {
+        throw new Error(`Unsafe file path "${filePath}".`);
+    }
+    const segments = filePath.split('/');
+    if (segments.length === 0)
+        throw new Error(`Unsafe file path "${filePath}".`);
+    assertSafeFileName(segments.at(-1) ?? '');
+    const folder = segments.slice(0, -1).join('/');
+    if (folder !== '') {
+        const problem = folderPathError(folder);
+        if (problem)
+            throw new Error(problem);
+    }
+}
+/**
+ * Turn an arbitrary uploaded file name (spaces, umlauts, parentheses, nested
+ * paths) into a safe single segment: strip the directory, transliterate to
+ * ASCII-ish, replace runs of disallowed characters with `-`, and lower-case
+ * the extension. Never throws for a normal image name.
+ */
+export function sanitizeFileName(original) {
+    const base = original.split(/[\\/]/).pop() ?? original;
+    const dot = base.lastIndexOf('.');
+    const rawStem = dot > 0 ? base.slice(0, dot) : base;
+    const rawExtension = dot > 0 ? base.slice(dot + 1) : '';
+    let stem = rawStem
+        .normalize('NFKD')
+        .replace(/[^a-zA-Z0-9._-]+/g, '-')
+        .replace(/-{2,}/g, '-')
+        .replace(/^[-.]+|[-.]+$/g, '');
+    if (!stem)
+        stem = 'asset';
+    if (!/^[a-zA-Z0-9]/.test(stem))
+        stem = `raw-${stem}`;
+    const extension = rawExtension.toLowerCase().replace(/[^a-z0-9]/g, '');
+    return extension ? `${stem}.${extension}` : stem;
+}
+export function sha256Hex(bytes) {
+    return createHash('sha256').update(bytes).digest('hex');
+}
+export class LibraryStore {
+    #config;
+    #registry;
+    // `read()` bypasses the queue and separate calls are not transactionally
+    // atomic; that tradeoff is intentional for this single-user development tool.
+    // Serializes mutations: every mutating operation chains onto the previous
+    // one's completion, so two concurrently handled requests can't interleave
+    // their read → modify → write cycles and lose one of the updates.
+    #queue = Promise.resolve();
+    constructor(config, registry = serverPluginsByType) {
+        this.#config = config;
+        this.#registry = registry;
+    }
+    get config() {
+        return this.#config;
+    }
+    /** Run a mutation after every previously enqueued one has settled. */
+    #enqueue(operation) {
+        const run = this.#queue.then(operation, operation);
+        this.#queue = run.then(() => { }, () => { });
+        return run;
+    }
+    /** Read + parse the library file; a missing file is an empty library. */
+    async read() {
+        if (!existsSync(this.#config.library))
+            return createEmptyLibrary();
+        return parseLibrary(await readFile(this.#config.library, 'utf8'));
+    }
+    /** Deterministically serialize + write the library file. */
+    async write(library) {
+        await mkdir(join(this.#config.library, '..'), { recursive: true });
+        const temporaryPath = `${this.#config.library}.tmp`;
+        await writeFile(temporaryPath, serializeLibrary(library));
+        await rename(temporaryPath, this.#config.library);
+    }
+    /**
+     * Ingest a new asset: write the raw file into `rawDir` (under a sanitized,
+     * non-colliding name), hash its content, and create the library record with
+     * the owning plugin's default parameters. Returns the updated library.
+     */
+    async ingest(options) {
+        return this.#enqueue(() => this.#ingest(options));
+    }
+    async #ingest(options) {
+        const idProblem = assetIdError(options.id);
+        if (idProblem)
+            throw new Error(idProblem);
+        const plugin = serverPluginForType(options.type, this.#registry);
+        const extension = extname(sanitizeFileName(options.fileName)).slice(1).toLowerCase();
+        if (!plugin.descriptor.accepts.includes(extension)) {
+            throw new Error(`The ${options.type} type does not accept ".${extension}" files (accepts: ${plugin.descriptor.accepts.join(', ')}).`);
+        }
+        const library = await this.read();
+        if (Object.hasOwn(library.assets, options.id)) {
+            throw new Error(`An asset with id "${options.id}" already exists.`);
+        }
+        const folder = options.folder === undefined ? '' : normalizeFolderPath(options.folder);
+        this.#requireFolder(library, folder);
+        const rawDirectory = join(this.#config.rawDir, folder);
+        await mkdir(rawDirectory, { recursive: true });
+        const storedName = this.#uniqueRawName(sanitizeFileName(options.fileName), folder);
+        const storedPath = folder === '' ? storedName : `${folder}/${storedName}`;
+        await writeFile(join(this.#config.rawDir, storedPath), options.bytes);
+        const record = {
+            type: options.type,
+            raw: storedPath,
+            rawHash: sha256Hex(options.bytes),
+            parameters: plugin.descriptor.defaultParameters(plugin.pluginConfig(this.#config)),
+            manifests: []
+        };
+        library.assets[options.id] = record;
+        await this.write(library);
+        return library;
+    }
+    /** Replace an asset's parameters (validated by the owning plugin). */
+    async updateParameters(id, parameters) {
+        return this.#enqueue(() => this.#updateParameters(id, parameters));
+    }
+    async #updateParameters(id, parameters) {
+        const library = await this.read();
+        const record = this.#requireAsset(library, id);
+        record.parameters = serverPluginForType(record.type, this.#registry).descriptor.validateParameters(parameters);
+        await this.write(library);
+        return library;
+    }
+    /** Replace an asset's manifest membership (every name must exist). */
+    async setManifests(id, manifests) {
+        return this.#enqueue(() => this.#setManifests(id, manifests));
+    }
+    async #setManifests(id, manifests) {
+        const library = await this.read();
+        const record = this.#requireAsset(library, id);
+        const unique = [...new Set(manifests)];
+        for (const name of unique) {
+            if (!Object.hasOwn(library.manifests, name)) {
+                throw new Error(`Unknown manifest "${name}".`);
+            }
+        }
+        record.manifests = unique.sort();
+        await this.write(library);
+        return library;
+    }
+    /** Rename an asset id (the raw file keeps its name — ids are the stable key). */
+    async renameAsset(id, newId) {
+        return this.#enqueue(() => this.#renameAsset(id, newId));
+    }
+    async #renameAsset(id, newId) {
+        const idProblem = assetIdError(newId);
+        if (idProblem)
+            throw new Error(idProblem);
+        const library = await this.read();
+        const record = this.#requireAsset(library, id);
+        if (newId === id)
+            return library;
+        if (Object.hasOwn(library.assets, newId)) {
+            throw new Error(`An asset with id "${newId}" already exists.`);
+        }
+        delete library.assets[id];
+        library.assets[newId] = record;
+        await this.write(library);
+        // The old id's proxies are orphans now; delete eagerly (pruning also covers it).
+        await this.#deleteProxiesOf(id);
+        return library;
+    }
+    /** Move an asset's raw file and current proxies without changing its stable id. */
+    async moveAsset(id, folder) {
+        return this.#enqueue(() => this.#moveAsset(id, folder));
+    }
+    async #moveAsset(id, requestedFolder) {
+        const folder = normalizeFolderPath(requestedFolder);
+        const library = await this.read();
+        const record = this.#requireAsset(library, id);
+        this.#requireFolder(library, folder);
+        const currentFolder = folderOfRawPath(record.raw);
+        if (folder === currentFolder)
+            return library;
+        const fileName = rawFileNameOfPath(record.raw);
+        const nextRaw = folder === '' ? fileName : `${folder}/${fileName}`;
+        const nextRawPath = join(this.#config.rawDir, nextRaw);
+        if (existsSync(nextRawPath)) {
+            throw new Error(`Raw file "${nextRaw}" already exists.`);
+        }
+        await ensureManagedFolder(this.#config.rawDir, folder);
+        await ensureManagedFolder(this.#config.proxyDir, folder);
+        const movedProxies = [];
+        let rawMoved = false;
+        try {
+            await rename(join(this.#config.rawDir, record.raw), nextRawPath);
+            rawMoved = true;
+            for (const relativePath of await listRelativeFiles(this.#config.proxyDir, currentFolder)) {
+                if (folderOfRawPath(relativePath) !== currentFolder)
+                    continue;
+                const proxyFileName = rawFileNameOfPath(relativePath);
+                if (!isProxyFileNameFor(id, proxyFileName))
+                    continue;
+                const nextRelativePath = folder === '' ? proxyFileName : `${folder}/${proxyFileName}`;
+                await rename(join(this.#config.proxyDir, relativePath), join(this.#config.proxyDir, nextRelativePath));
+                movedProxies.push({ from: relativePath, to: nextRelativePath });
+            }
+            record.raw = nextRaw;
+            await this.write(library);
+        }
+        catch (cause) {
+            record.raw = currentFolder === '' ? fileName : `${currentFolder}/${fileName}`;
+            for (const proxy of movedProxies.reverse()) {
+                await rename(join(this.#config.proxyDir, proxy.to), join(this.#config.proxyDir, proxy.from));
+            }
+            if (rawMoved)
+                await rename(nextRawPath, join(this.#config.rawDir, record.raw));
+            throw cause;
+        }
+        return library;
+    }
+    async createFolder(path) {
+        return this.#enqueue(() => this.#createFolder(path));
+    }
+    async #createFolder(requestedPath) {
+        const path = normalizeFolderPath(requestedPath);
+        const problem = folderPathError(path);
+        if (problem)
+            throw new Error(problem);
+        const library = await this.read();
+        const parent = parentFolderPath(path);
+        this.#requireFolder(library, parent);
+        this.#assertFolderAvailable(library, path);
+        library.folders.push(path);
+        library.folders.sort();
+        await Promise.all([
+            ensureManagedFolder(this.#config.rawDir, path),
+            ensureManagedFolder(this.#config.proxyDir, path)
+        ]);
+        await this.write(library);
+        return library;
+    }
+    async renameFolder(path, newName) {
+        return this.#enqueue(() => this.#renameFolder(path, newName));
+    }
+    async #renameFolder(requestedPath, requestedName) {
+        const path = normalizeFolderPath(requestedPath);
+        const newName = requestedName.normalize('NFC');
+        const nameProblem = folderNameError(newName);
+        if (nameProblem)
+            throw new Error(nameProblem);
+        const parent = parentFolderPath(path);
+        const nextPath = joinFolderPath(parent, newName);
+        return this.#relocateFolder(path, nextPath);
+    }
+    /** Move a complete folder subtree below another folder (or the implicit root). */
+    async moveFolder(path, parent) {
+        return this.#enqueue(() => this.#moveFolder(path, parent));
+    }
+    async #moveFolder(requestedPath, requestedParent) {
+        const path = normalizeFolderPath(requestedPath);
+        const parent = normalizeFolderPath(requestedParent);
+        const nextPath = joinFolderPath(parent, folderNameOf(path));
+        return this.#relocateFolder(path, nextPath);
+    }
+    async #relocateFolder(path, nextPath) {
+        const library = await this.read();
+        this.#requireFolder(library, path, false);
+        const nextParent = parentFolderPath(nextPath);
+        this.#requireFolder(library, nextParent);
+        if (isFolderOrDescendant(nextParent, path)) {
+            throw new Error(`Folder "${path}" cannot be moved into itself or one of its descendants.`);
+        }
+        if (nextPath === path)
+            return library;
+        this.#assertFolderAvailable(library, nextPath, path);
+        const renamedFolders = library.folders.map((folder) => isFolderOrDescendant(folder, path) ? replaceFolderPrefix(folder, path, nextPath) : folder);
+        const renamedKeys = new Set();
+        for (const folder of renamedFolders) {
+            const key = portableFolderPathKey(folder);
+            if (renamedKeys.has(key))
+                throw new Error(`Folder rename would collide at "${folder}".`);
+            renamedKeys.add(key);
+        }
+        const rawFrom = join(this.#config.rawDir, path);
+        const rawTo = join(this.#config.rawDir, nextPath);
+        const proxyFrom = join(this.#config.proxyDir, path);
+        const proxyTo = join(this.#config.proxyDir, nextPath);
+        await mkdir(join(rawTo, '..'), { recursive: true });
+        await mkdir(join(proxyTo, '..'), { recursive: true });
+        const caseOnly = portableFolderPathKey(path) === portableFolderPathKey(nextPath);
+        const rawTemporary = caseOnly ? `${rawFrom}.fundus-${crypto.randomUUID()}` : rawFrom;
+        const proxyTemporary = caseOnly ? `${proxyFrom}.fundus-${crypto.randomUUID()}` : proxyFrom;
+        if (caseOnly) {
+            await rename(rawFrom, rawTemporary);
+            try {
+                await rename(proxyFrom, proxyTemporary);
+            }
+            catch (cause) {
+                await rename(rawTemporary, rawFrom);
+                throw cause;
+            }
+        }
+        try {
+            await rename(rawTemporary, rawTo);
+            try {
+                await rename(proxyTemporary, proxyTo);
+            }
+            catch (cause) {
+                if (caseOnly) {
+                    await rename(rawTo, rawTemporary);
+                    await rename(rawTemporary, rawFrom);
+                    await rename(proxyTemporary, proxyFrom);
+                }
+                else {
+                    await rename(rawTo, rawFrom);
+                }
+                throw cause;
+            }
+        }
+        catch (cause) {
+            if (caseOnly) {
+                if (existsSync(rawTemporary))
+                    await rename(rawTemporary, rawFrom);
+                if (existsSync(proxyTemporary))
+                    await rename(proxyTemporary, proxyFrom);
+            }
+            throw cause;
+        }
+        library.folders = renamedFolders.sort();
+        for (const record of Object.values(library.assets)) {
+            const assetFolder = folderOfRawPath(record.raw);
+            if (!isFolderOrDescendant(assetFolder, path))
+                continue;
+            const movedFolder = replaceFolderPrefix(assetFolder, path, nextPath);
+            record.raw = `${movedFolder}/${rawFileNameOfPath(record.raw)}`;
+        }
+        try {
+            await this.write(library);
+        }
+        catch (cause) {
+            if (caseOnly) {
+                await rename(rawTo, rawTemporary);
+                await rename(proxyTo, proxyTemporary);
+                await rename(rawTemporary, rawFrom);
+                await rename(proxyTemporary, proxyFrom);
+            }
+            else {
+                await rename(rawTo, rawFrom);
+                await rename(proxyTo, proxyFrom);
+            }
+            throw cause;
+        }
+        return library;
+    }
+    /** Recursively delete a folder and every asset stored below it. */
+    async deleteFolder(path) {
+        return this.#enqueue(() => this.#deleteFolder(path));
+    }
+    async #deleteFolder(requestedPath) {
+        const path = normalizeFolderPath(requestedPath);
+        const library = await this.read();
+        this.#requireFolder(library, path, false);
+        const deletedAssetIds = Object.entries(library.assets)
+            .filter(([, record]) => isFolderOrDescendant(folderOfRawPath(record.raw), path))
+            .map(([id]) => id)
+            .sort();
+        for (const id of deletedAssetIds)
+            delete library.assets[id];
+        library.folders = library.folders.filter((folder) => !isFolderOrDescendant(folder, path));
+        const token = crypto.randomUUID();
+        const rawPath = join(this.#config.rawDir, path);
+        const proxyPath = join(this.#config.proxyDir, path);
+        const rawTemporary = join(this.#config.rawDir, `.fundus-delete-${token}`);
+        const proxyTemporary = join(this.#config.proxyDir, `.fundus-delete-${token}`);
+        await rename(rawPath, rawTemporary);
+        try {
+            await rename(proxyPath, proxyTemporary);
+        }
+        catch (cause) {
+            await rename(rawTemporary, rawPath);
+            throw cause;
+        }
+        try {
+            await this.write(library);
+        }
+        catch (cause) {
+            await rename(rawTemporary, rawPath);
+            await rename(proxyTemporary, proxyPath);
+            throw cause;
+        }
+        await Promise.all([
+            rm(rawTemporary, { recursive: true, force: true }),
+            rm(proxyTemporary, { recursive: true, force: true })
+        ]);
+        return { library, deletedAssetIds };
+    }
+    /** Delete an asset: remove the record, its raw file, and its proxies. */
+    async deleteAsset(id) {
+        return this.#enqueue(() => this.#deleteAsset(id));
+    }
+    async #deleteAsset(id) {
+        return this.#deleteAssets([id]);
+    }
+    /** Delete several assets as one library/file transaction. */
+    async deleteAssets(ids) {
+        return this.#enqueue(() => this.#deleteAssets(ids));
+    }
+    async #deleteAssets(ids) {
+        const uniqueIds = [...new Set(ids)];
+        if (uniqueIds.length === 0)
+            throw new Error('At least one asset id is required.');
+        const library = await this.read();
+        const records = uniqueIds.map((id) => ({ id, record: this.#requireAsset(library, id) }));
+        const deletedIds = new Set(uniqueIds);
+        const token = crypto.randomUUID();
+        const rawTemporaryRoot = join(this.#config.rawDir, `.fundus-delete-assets-${token}`);
+        const proxyTemporaryRoot = join(this.#config.proxyDir, `.fundus-delete-assets-${token}`);
+        const movedRawPaths = [];
+        const movedProxyPaths = [];
+        const stageFile = async (root, temporaryRoot, relativePath) => {
+            const source = join(root, relativePath);
+            if (!existsSync(source))
+                return;
+            const target = join(temporaryRoot, relativePath);
+            await mkdir(dirname(target), { recursive: true });
+            await rename(source, target);
+        };
+        const restoreFiles = async (root, temporaryRoot, relativePaths) => {
+            for (const relativePath of [...relativePaths].reverse()) {
+                const source = join(temporaryRoot, relativePath);
+                if (!existsSync(source))
+                    continue;
+                const target = join(root, relativePath);
+                await mkdir(dirname(target), { recursive: true });
+                await rename(source, target);
+            }
+        };
+        try {
+            for (const { record } of records) {
+                await stageFile(this.#config.rawDir, rawTemporaryRoot, record.raw);
+                movedRawPaths.push(record.raw);
+            }
+            if (existsSync(this.#config.proxyDir)) {
+                for (const relativePath of await listRelativeFiles(this.#config.proxyDir)) {
+                    if ([...deletedIds].some((id) => isProxyFileNameFor(id, rawFileNameOfPath(relativePath)))) {
+                        await stageFile(this.#config.proxyDir, proxyTemporaryRoot, relativePath);
+                        movedProxyPaths.push(relativePath);
+                    }
+                }
+            }
+            for (const id of uniqueIds)
+                delete library.assets[id];
+            await this.write(library);
+        }
+        catch (cause) {
+            await restoreFiles(this.#config.proxyDir, proxyTemporaryRoot, movedProxyPaths);
+            await restoreFiles(this.#config.rawDir, rawTemporaryRoot, movedRawPaths);
+            await Promise.all([
+                rm(rawTemporaryRoot, { recursive: true, force: true }),
+                rm(proxyTemporaryRoot, { recursive: true, force: true })
+            ]);
+            throw cause;
+        }
+        await Promise.all([
+            rm(rawTemporaryRoot, { recursive: true, force: true }),
+            rm(proxyTemporaryRoot, { recursive: true, force: true })
+        ]);
+        return library;
+    }
+    async createManifest(name) {
+        return this.#enqueue(() => this.#createManifest(name));
+    }
+    async #createManifest(name) {
+        const nameProblem = manifestNameError(name);
+        if (nameProblem) {
+            throw new Error(nameProblem);
+        }
+        const library = await this.read();
+        if (Object.hasOwn(library.manifests, name)) {
+            throw new Error(`A manifest named "${name}" already exists.`);
+        }
+        // Module file names are the kebab form of the manifest name, so two names
+        // sharing a kebab form (`mainCatalog` / `mainCATALOG` → `main-catalog`) would write
+        // the same generated module — reject the collision at the source.
+        const fileName = manifestModuleFileName(name);
+        for (const existingName of Object.keys(library.manifests)) {
+            if (manifestModuleFileName(existingName) === fileName) {
+                throw new Error(`Manifest "${name}" would generate the same module ("${fileName}") as the existing ` +
+                    `manifest "${existingName}" — pick a name with a distinct kebab-case form.`);
+            }
+        }
+        library.manifests[name] = {};
+        await this.write(library);
+        return library;
+    }
+    /**
+     * Set (or clear) a manifest's editor appearance — its color and/or emoji.
+     * An `undefined` field is left unchanged; a `null` field clears it. Values
+     * are validated against the fixed palettes.
+     */
+    async setManifestAppearance(name, appearance) {
+        return this.#enqueue(() => this.#setManifestAppearance(name, appearance));
+    }
+    async #setManifestAppearance(name, appearance) {
+        const library = await this.read();
+        if (!Object.hasOwn(library.manifests, name)) {
+            throw new Error(`Unknown manifest "${name}".`);
+        }
+        const record = library.manifests[name];
+        if (appearance.color !== undefined) {
+            if (appearance.color === null) {
+                delete record.color;
+            }
+            else {
+                const problem = manifestColorError(appearance.color);
+                if (problem)
+                    throw new Error(problem);
+                record.color = appearance.color;
+            }
+        }
+        if (appearance.emoji !== undefined) {
+            if (appearance.emoji === null) {
+                delete record.emoji;
+            }
+            else {
+                const problem = manifestEmojiError(appearance.emoji);
+                if (problem)
+                    throw new Error(problem);
+                record.emoji = appearance.emoji;
+            }
+        }
+        await this.write(library);
+        return library;
+    }
+    /** Rename a manifest and rewrite every asset's membership to the new name. */
+    async renameManifest(name, newName) {
+        return this.#enqueue(() => this.#renameManifest(name, newName));
+    }
+    async #renameManifest(name, newName) {
+        const nameProblem = manifestNameError(newName);
+        if (nameProblem) {
+            throw new Error(nameProblem);
+        }
+        const library = await this.read();
+        if (!Object.hasOwn(library.manifests, name)) {
+            throw new Error(`Unknown manifest "${name}".`);
+        }
+        if (newName === name)
+            return library;
+        if (Object.hasOwn(library.manifests, newName)) {
+            throw new Error(`A manifest named "${newName}" already exists.`);
+        }
+        // Same kebab-collision guard as creation — the renamed manifest itself is
+        // exempt (a pure case change keeps the module file name and is fine).
+        const fileName = manifestModuleFileName(newName);
+        for (const existingName of Object.keys(library.manifests)) {
+            if (existingName !== name && manifestModuleFileName(existingName) === fileName) {
+                throw new Error(`Manifest "${newName}" would generate the same module ("${fileName}") as the existing ` +
+                    `manifest "${existingName}" — pick a name with a distinct kebab-case form.`);
+            }
+        }
+        const record = library.manifests[name];
+        delete library.manifests[name];
+        library.manifests[newName] = record;
+        for (const assetRecord of Object.values(library.assets)) {
+            if (assetRecord.manifests.includes(name)) {
+                assetRecord.manifests = assetRecord.manifests
+                    .map((manifest) => (manifest === name ? newName : manifest))
+                    .sort();
+            }
+        }
+        await this.write(library);
+        return library;
+    }
+    /** Delete a manifest and strip it from every asset's membership. */
+    async deleteManifest(name) {
+        return this.#enqueue(() => this.#deleteManifest(name));
+    }
+    async #deleteManifest(name) {
+        const library = await this.read();
+        if (!Object.hasOwn(library.manifests, name)) {
+            throw new Error(`Unknown manifest "${name}".`);
+        }
+        delete library.manifests[name];
+        for (const record of Object.values(library.assets)) {
+            record.manifests = record.manifests.filter((manifest) => manifest !== name);
+        }
+        await this.write(library);
+        return library;
+    }
+    /**
+     * Structural + referential validation, listed per asset: invalid id, unknown
+     * type, dangling raw pointer, invalid parameters, unknown manifest names,
+     * and reference errors (dangling target, type mismatch, cycles).
+     */
+    async validate(library) {
+        const issues = [];
+        const folderKeys = new Map();
+        for (const folder of library.folders) {
+            const problem = folderPathError(folder);
+            if (problem)
+                issues.push({ message: problem });
+            if (folder !== normalizeFolderPath(folder)) {
+                issues.push({ message: `Folder path "${folder}" is not Unicode-normalized.` });
+            }
+            const key = portableFolderPathKey(folder);
+            const collision = folderKeys.get(key);
+            if (collision !== undefined) {
+                issues.push({ message: `Folders "${collision}" and "${folder}" collide on disk.` });
+            }
+            else {
+                folderKeys.set(key, folder);
+            }
+            const parent = parentFolderPath(folder);
+            if (parent !== '' && !library.folders.includes(parent)) {
+                issues.push({ message: `Folder "${folder}" has missing parent "${parent}".` });
+            }
+            for (const root of [this.#config.rawDir, this.#config.proxyDir]) {
+                if (!existsSync(join(root, folder, '.gitkeep'))) {
+                    issues.push({
+                        message: `Folder "${folder}" is not mirrored with a .gitkeep in ${root}.`
+                    });
+                }
+            }
+        }
+        for (const [name, record] of Object.entries(library.manifests)) {
+            const nameProblem = manifestNameError(name);
+            if (nameProblem)
+                issues.push({ message: nameProblem });
+            if (record.color !== undefined) {
+                const colorProblem = manifestColorError(record.color);
+                if (colorProblem)
+                    issues.push({ message: `Manifest "${name}": ${colorProblem}` });
+            }
+            if (record.emoji !== undefined) {
+                const emojiProblem = manifestEmojiError(record.emoji);
+                if (emojiProblem)
+                    issues.push({ message: `Manifest "${name}": ${emojiProblem}` });
+            }
+        }
+        const namesByModuleFile = new Map();
+        for (const name of Object.keys(library.manifests)) {
+            const fileName = manifestModuleFileName(name);
+            const existingName = namesByModuleFile.get(fileName);
+            if (existingName !== undefined) {
+                issues.push({
+                    message: `Manifests "${existingName}" and "${name}" would both generate "${fileName}".`
+                });
+            }
+            else {
+                namesByModuleFile.set(fileName, name);
+            }
+        }
+        for (const [assetId, record] of Object.entries(library.assets)) {
+            const idProblem = assetIdError(assetId);
+            if (idProblem)
+                issues.push({ assetId, message: idProblem });
+            const plugin = this.#registry[record.type];
+            if (!plugin) {
+                issues.push({ assetId, message: `Unknown asset type "${record.type}".` });
+            }
+            else {
+                try {
+                    plugin.descriptor.validateParameters(record.parameters);
+                }
+                catch (cause) {
+                    issues.push({
+                        assetId,
+                        message: `Invalid parameters: ${cause instanceof Error ? cause.message : String(cause)}`
+                    });
+                }
+            }
+            try {
+                assertSafeRelativeFilePath(record.raw);
+            }
+            catch (cause) {
+                issues.push({
+                    assetId,
+                    message: cause instanceof Error ? cause.message : String(cause)
+                });
+            }
+            const assetFolder = folderOfRawPath(record.raw);
+            if (assetFolder !== '' && !library.folders.includes(assetFolder)) {
+                issues.push({ assetId, message: `Unknown asset folder "${assetFolder}".` });
+            }
+            if (!existsSync(join(this.#config.rawDir, record.raw))) {
+                issues.push({
+                    assetId,
+                    message: `Raw file "${record.raw}" is missing from the raw directory.`
+                });
+            }
+            for (const manifest of record.manifests) {
+                if (!library.manifests[manifest]) {
+                    issues.push({ assetId, message: `Unknown manifest "${manifest}".` });
+                }
+            }
+        }
+        issues.push(...referenceErrors(library, collectAllReferences(library, descriptorsByType(this.#registry))));
+        return issues;
+    }
+    async #deleteProxiesOf(assetId) {
+        if (!existsSync(this.#config.proxyDir))
+            return;
+        for (const relativePath of await listRelativeFiles(this.#config.proxyDir)) {
+            if (isProxyFileNameFor(assetId, rawFileNameOfPath(relativePath))) {
+                await unlink(join(this.#config.proxyDir, relativePath));
+            }
+        }
+    }
+    async syncFolders(library) {
+        await syncManagedFolders(this.#config, library);
+    }
+    #requireAsset(library, id) {
+        // Own-property check: an inherited key ("constructor", …) must not
+        // resolve to an Object.prototype member and pass as a record.
+        if (!Object.hasOwn(library.assets, id)) {
+            throw new Error(`Unknown asset "${id}".`);
+        }
+        return library.assets[id];
+    }
+    /** Resolve a non-colliding raw file name, appending `-1`, `-2`, … before the extension. */
+    #uniqueRawName(fileName, folder) {
+        if (!existsSync(join(this.#config.rawDir, folder, fileName)))
+            return fileName;
+        const extension = extname(fileName);
+        const stem = fileName.slice(0, fileName.length - extension.length);
+        for (let index = 1;; index++) {
+            const candidate = `${stem}-${index}${extension}`;
+            if (!existsSync(join(this.#config.rawDir, folder, candidate)))
+                return candidate;
+        }
+    }
+    #requireFolder(library, folder, allowRoot = true) {
+        if (folder === '' && allowRoot)
+            return;
+        if (!library.folders.includes(folder))
+            throw new Error(`Unknown folder "${folder}".`);
+    }
+    #assertFolderAvailable(library, path, except) {
+        const key = portableFolderPathKey(path);
+        const collision = library.folders.find((folder) => folder !== except && portableFolderPathKey(folder) === key);
+        if (collision !== undefined) {
+            throw new Error(`Folder "${path}" collides with existing folder "${collision}".`);
+        }
+    }
+}