@feralfile/cli 2.3.0 → 2.4.0

package/dist/index.js

@@ -28,6 +28,7 @@ const play_1 = require("./src/commands/play");
 const publish_1 = require("./src/commands/publish");
 const find_1 = require("./src/commands/find");
 const build_1 = require("./src/commands/build");
+const enrich_1 = require("./src/commands/enrich");
 const config_1 = require("./src/commands/config");
 const ssh_1 = require("./src/commands/ssh");
 const device_1 = require("./src/commands/device");
@@ -55,6 +56,7 @@ program.addCommand(sign_1.signCommand);
 program.addCommand(play_1.playCommand);
 program.addCommand(publish_1.publishCommand);
 program.addCommand(find_1.findCommand);
+program.addCommand(enrich_1.enrichCommand);
 program.addCommand(build_1.buildCommand);
 program.addCommand(config_1.configCommand);
 program.addCommand(ssh_1.sshCommand);

package/dist/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@feralfile/cli",
-    "version": "2.3.0",
+    "version": "2.4.0",
     "description": "CLI for building, signing, and playing DP-1 playlists of digital art on Feral File devices",
     "repository": {
         "type": "git",

package/dist/src/commands/enrich.js

@@ -0,0 +1,315 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.enrichCommand = void 0;
+const commander_1 = require("commander");
+const chalk_1 = __importDefault(require("chalk"));
+const fs_1 = require("fs");
+const crypto_1 = require("crypto");
+const path_1 = require("path");
+const enrich_playlist_1 = require("../utilities/enrich-playlist");
+const playlist_verifier_1 = require("../utilities/playlist-verifier");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const { getNFTTokenInfoBatch } = require('../utilities/nft-indexer');
+/**
+ * writePlaylistAtomically replaces a file only once the new bytes are safely on
+ * disk.
+ *
+ * The default destination is the input file, and a plain write truncates it
+ * first. Enrichment runs after a lookup that can take minutes while the indexer
+ * warms tokens, so the window between truncation and a complete write is a
+ * window in which an interruption, a full disk, or an I/O error leaves the
+ * curator with an empty or half-written playlist and no copy of what they had.
+ * A rename within the same directory is atomic, so the original file survives
+ * intact until the replacement is complete.
+ *
+ * The temporary file is created alongside the destination rather than in the
+ * system temp directory: rename is only atomic within a filesystem, and those
+ * are not guaranteed to be the same one.
+ */
+async function writePlaylistAtomically(destination, contents, expectedDigest) {
+    // Follow a symlink to its target before replacing anything. rename() would
+    // replace the link itself, silently detaching a playlist that other paths
+    // reach through that name while reporting success.
+    let target = destination;
+    const existing = await fs_1.promises.lstat(destination).catch(() => null);
+    if (existing?.isSymbolicLink()) {
+        target = await fs_1.promises.realpath(destination);
+    }
+    const temporary = (0, path_1.join)((0, path_1.dirname)(target), `.${(0, path_1.basename)(target)}.${process.pid}.${(0, crypto_1.randomBytes)(4).toString('hex')}.tmp`);
+    // The destination's mode has to be known before the file exists, not after
+    // it holds the contents. Creating at the default 0o666-minus-umask and
+    // chmod'ing afterwards leaves the enriched playlist readable by other local
+    // users for the length of the write — short, but a disclosure window on a
+    // file the curator deliberately restricted.
+    const current = await fs_1.promises.stat(target).catch(() => null);
+    const mode = current ? current.mode & 0o7777 : undefined;
+    try {
+        // 'wx' fails rather than truncating if the name somehow exists, so a
+        // collision can never destroy another process's work in progress.
+        const handle = await fs_1.promises.open(temporary, 'wx', mode);
+        try {
+            // open() applies the mode through umask, which can strip bits the
+            // destination had. chmod is not subject to umask, so this restores the
+            // exact mode — still before any bytes are written.
+            if (mode !== undefined) {
+                await handle.chmod(mode);
+            }
+            // A replacement is a new inode, so it carries this process's ownership
+            // rather than the destination's. Silently reassigning a playlist that
+            // belongs to another user or a shared group can lock collaborators out
+            // of it, or widen who can reach it. Carry the ownership across, and when
+            // that is not permitted refuse the in-place replacement instead of
+            // completing it with different access than the file had.
+            if (current && (current.uid !== process.getuid?.() || current.gid !== process.getgid?.())) {
+                try {
+                    await handle.chown(current.uid, current.gid);
+                }
+                catch {
+                    await fs_1.promises.rm(temporary, { force: true }).catch(() => undefined);
+                    throw new OwnershipError(target);
+                }
+            }
+            await handle.writeFile(contents);
+            // rename() is atomic against concurrent readers but says nothing about
+            // power loss: the directory entry can reach disk before the data it
+            // points at. Without this a crash mid-write can leave the playlist
+            // present and empty, which is the outcome the temporary file exists to
+            // prevent. Sync the contents first, then the directory entry after.
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+        // Checked here, as late as the sequence allows: everything expensive is
+        // already done, so the interval between this read and the rename below is
+        // a few syscalls rather than the minutes a lookup takes.
+        //
+        // It narrows the race; it cannot close it. Comparing and then replacing is
+        // not atomic against an editor that does not participate in any protocol,
+        // and nothing available in userspace makes it so — every tool that edits a
+        // file in place carries this. Passing no digest (a distinct --output) opts
+        // out entirely, which is the safe path when a file is being actively
+        // edited.
+        if (expectedDigest !== undefined) {
+            const current = await fs_1.promises.readFile(target).catch(() => null);
+            const digest = current && (0, crypto_1.createHash)('sha256').update(current).digest('hex');
+            if (digest !== expectedDigest) {
+                await fs_1.promises.rm(temporary, { force: true }).catch(() => undefined);
+                return false;
+            }
+        }
+        await fs_1.promises.rename(temporary, target);
+        await syncDirectory((0, path_1.dirname)(target));
+        return true;
+    }
+    catch (error) {
+        await fs_1.promises.rm(temporary, { force: true }).catch(() => undefined);
+        throw error;
+    }
+}
+/**
+ * OwnershipError marks a refusal to replace a file whose ownership this
+ * process cannot reproduce, so the caller can explain it rather than print a
+ * bare errno.
+ */
+class OwnershipError extends Error {
+    target;
+    constructor(target) {
+        super(`cannot preserve ownership of ${target}`);
+        this.target = target;
+        this.name = 'OwnershipError';
+    }
+}
+/**
+ * isSameFile reports whether two paths name the same file on disk.
+ *
+ * Compares resolved paths rather than the strings the caller typed, so
+ * `-o ./playlist.json` against `playlist.json`, and a symlink against its
+ * target, are recognized as the in-place case they are.
+ */
+async function isSameFile(a, b) {
+    if (a === b) {
+        return true;
+    }
+    const [left, right] = await Promise.all([
+        fs_1.promises.realpath(a).catch(() => null),
+        fs_1.promises.realpath(b).catch(() => null),
+    ]);
+    return left !== null && left === right;
+}
+/**
+ * syncDirectory flushes a directory entry so a rename survives power loss.
+ *
+ * Best-effort by design. Directory fsync is not portable — Windows rejects it
+ * outright — and a durability barrier that cannot be raised is not a reason to
+ * fail a write that has already succeeded. The data itself was synced before
+ * the rename, so the worst case here is the old name surviving a crash, not a
+ * corrupt file.
+ */
+async function syncDirectory(directory) {
+    try {
+        const handle = await fs_1.promises.open(directory, 'r');
+        try {
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    catch {
+        /* not supported on this platform or filesystem */
+    }
+}
+/**
+ * reportInvalid prints structural validation diagnostics and exits non-zero.
+ *
+ * Enrichment refuses to work on a document DP-1 rejects, and refuses to write
+ * one. Writing an invalid playlist would replace the operator's file with
+ * something sign, publish, and play all reject later, having reported success.
+ */
+function reportInvalid(stage, result) {
+    console.error(chalk_1.default.red(`\n${stage}`));
+    if (result.error) {
+        console.error(chalk_1.default.dim(`  ${result.error}`));
+    }
+    for (const detail of result.details ?? []) {
+        console.error(chalk_1.default.dim(`  ${detail.path}: ${detail.message}`));
+    }
+    console.error(chalk_1.default.dim('\n  The file was left unchanged.\n'));
+    process.exit(1);
+}
+/**
+ * SKIP_COPY explains each skip in the operator's terms rather than the code's.
+ * `no-provenance` is the one a person can act on, so it says what to add.
+ */
+const SKIP_COPY = {
+    'already-labelled': 'already has a manifest (use --force to replace)',
+    'external-ref': 'carries an external ref, which outranks an inline manifest',
+    'no-provenance': 'no provenance.contract chain/address/tokenId to look up',
+    'ambiguous-chain': 'chain "evm" names a family; pass --assume-ethereum to assert the network',
+    // The indexer drops unresolved tokens from its response rather than
+    // reporting why, so there is no per-item reason to relay here.
+    'not-indexed': 'the indexer returned nothing for it',
+    'no-metadata': 'the indexer resolved it but has no artist, description, or still image',
+};
+exports.enrichCommand = new commander_1.Command('enrich')
+    .description('Add missing artist, title, and thumbnail metadata to a playlist')
+    .argument('<file>', 'Path to the DP-1 playlist file')
+    .option('-o, --output <filename>', 'Write here instead of overwriting the input')
+    .option('--force', 'Replace manifests that already exist', false)
+    .option('--assume-ethereum', 'Treat DP-1 "evm" coordinates as Ethereum. Without this they are skipped, ' +
+    'because "evm" names a family and the wrong member yields another artwork.', false)
+    .option('-v, --verbose', 'Show detailed output', false)
+    .action(async (file, options) => {
+    try {
+        console.log(chalk_1.default.blue('\nEnrich playlist\n'));
+        // Hash the exact bytes parsed, not a stat taken afterwards: an edit
+        // between the read and the stat would leave the snapshot describing
+        // newer content while enrichment still worked from the older bytes.
+        const original = await fs_1.promises.readFile(file);
+        const originalDigest = (0, crypto_1.createHash)('sha256').update(original).digest('hex');
+        const playlist = JSON.parse(original.toString('utf-8'));
+        const total = Array.isArray(playlist.items) ? playlist.items.length : 0;
+        if (total === 0) {
+            console.error(chalk_1.default.red('That playlist has no items.'));
+            process.exit(1);
+        }
+        // Validate before spending minutes on indexer lookups for a document
+        // that was never going to be writable.
+        const before = await (0, playlist_verifier_1.validatePlaylist)(playlist);
+        if (!before.valid) {
+            reportInvalid('That playlist is not valid DP-1:', before);
+        }
+        // Warming previously-unseen tokens can take minutes, so a human watching
+        // this needs to see it move. Matches the progress line `find` prints.
+        let printedProgress = false;
+        const onProgress = (done, count) => {
+            printedProgress = true;
+            process.stdout.write(chalk_1.default.dim(`\r  ${done}/${count} looked up...`));
+        };
+        // getNFTTokenInfoBatch is (tokens, duration, onProgress) — the second
+        // positional is DP-1 display seconds, not the callback. Enrichment never
+        // sets duration (the curator's timing is not ours to touch), so it is
+        // passed undefined and the callback goes third. find.ts carries the same
+        // warning; getting this wrong silently returns unusable results.
+        const lookup = (tokens, onProgressCallback) => getNFTTokenInfoBatch(tokens, undefined, onProgressCallback);
+        const result = await (0, enrich_playlist_1.enrichPlaylistManifests)(playlist, lookup, {
+            force: options.force,
+            assumeEthereum: options.assumeEthereum,
+            onProgress,
+        });
+        if (printedProgress) {
+            process.stdout.write('\n');
+        }
+        // Said before anything is written, so an operator who did not mean to
+        // assert the network still has the file they started with.
+        if (result.assumedEthereum > 0) {
+            console.log(chalk_1.default.yellow(`\n  ${result.assumedEthereum} coordinate(s) gave chain "evm" and were looked up on` +
+                `\n  Ethereum because --assume-ethereum was passed. An L2 work sharing an` +
+                `\n  address and token id with an Ethereum one would take the wrong metadata.`));
+        }
+        const destination = options.output ?? file;
+        // --output names a file the caller expects to find afterwards, so it is
+        // written even when nothing was enriched. Overwriting the input on a
+        // no-op would be pure risk for no gain, so that case still writes
+        // nothing.
+        const shouldWrite = result.enriched > 0 || options.output !== undefined;
+        if (shouldWrite) {
+            // Re-validate the enriched candidate. An inline manifest is schema-
+            // checked the same way a fetched one is (playlists extension §3.6), so
+            // a malformed manifest from the indexer must not reach the file.
+            const after = await (0, playlist_verifier_1.validatePlaylist)(result.playlist);
+            if (!after.valid) {
+                reportInvalid('Enrichment produced an invalid playlist:', after);
+            }
+            const replaced = await writePlaylistAtomically(destination, JSON.stringify(result.playlist, null, 2), (await isSameFile(file, destination)) ? originalDigest : undefined);
+            if (!replaced) {
+                console.error(chalk_1.default.red('\nThat playlist changed while the lookup ran.'));
+                console.error(chalk_1.default.dim('  Enrichment was computed from the earlier version, so writing it\n' +
+                    '  would discard whatever changed. Nothing was written. Re-run to\n' +
+                    '  enrich the current file, or pass -o to write somewhere else.\n'));
+                process.exit(1);
+            }
+        }
+        console.log(result.enriched > 0
+            ? chalk_1.default.green(`\n${result.enriched} of ${total} item(s) enriched`)
+            : chalk_1.default.yellow('\nNothing to enrich'));
+        if (shouldWrite) {
+            console.log(chalk_1.default.dim(`  Output: ${destination}`));
+        }
+        if (result.skipped.length > 0) {
+            const shown = options.verbose ? result.skipped : result.skipped.slice(0, 10);
+            console.log(chalk_1.default.dim(`\n  Skipped ${result.skipped.length}:`));
+            for (const skip of shown) {
+                console.log(chalk_1.default.dim(`    ${skip.title} — ${SKIP_COPY[skip.reason]}`));
+            }
+            if (shown.length < result.skipped.length) {
+                console.log(chalk_1.default.dim(`    ...and ${result.skipped.length - shown.length} more (-v to list)`));
+            }
+        }
+        // Say this loudly. A signed playlist that silently lost its envelope
+        // fails at the device, which is the worst place to discover it.
+        if (result.signatureInvalidated) {
+            console.log(chalk_1.default.yellow('\n  Signature removed — the document changed.'));
+            console.log(chalk_1.default.dim(`  Re-sign before playing: ff-cli sign ${destination}`));
+        }
+        console.log();
+    }
+    catch (error) {
+        if (error instanceof OwnershipError) {
+            console.error(chalk_1.default.red('\nThat playlist belongs to another user or group.'));
+            console.error(chalk_1.default.dim(`  Replacing it in place would hand it to you and could lock others out,\n` +
+                `  so nothing was written. Write elsewhere instead:\n` +
+                `    ff-cli enrich ${error.target} -o enriched.json\n`));
+            process.exit(1);
+        }
+        console.error(chalk_1.default.red('\nError:'), error.message);
+        if (options.verbose) {
+            console.error(chalk_1.default.dim(error.stack));
+        }
+        process.exit(1);
+    }
+});

package/dist/src/utilities/enrich-playlist.js

@@ -0,0 +1,459 @@
+"use strict";
+/**
+ * Fills in missing inline Ref Manifests on an existing DP-1 playlist.
+ *
+ * `find` and `build` attach an `inlineManifest` to every item they create, so
+ * playlists this CLI authors end to end are already labelled. Playlists that
+ * arrive any other way are not: items copied out of another playlist, items
+ * hand-written against a known contract, items inherited from a document
+ * predating §3.6. Those carry a `source` and a `provenance` block and nothing
+ * else, and there was no way to repair them short of editing JSON by hand.
+ *
+ * What the gap costs is visible on a device. The FF1 tombstone resolves its
+ * label through `ref` -> `inlineManifest` -> `item.metadata` and falls back to
+ * the item title, so an unlabelled item shows a title with no artist line. The
+ * app's grid is worse: it can rasterize a thumbnail from a direct image, video,
+ * or SVG source, but not from a live HTML work, so every generative item in an
+ * unlabelled playlist renders as an empty tile. A playlist of computational art
+ * is mostly live HTML, which is exactly the case that looks broken.
+ *
+ * Enrichment is additive and narrow on purpose. It writes `inlineManifest` and
+ * nothing else: `source`, `duration`, `id`, and `display` are the curator's
+ * decisions and are left exactly as found, even when the indexer disagrees. An
+ * item the indexer cannot resolve is reported, never guessed at — a fabricated
+ * artist line in a signed document is worse than a missing one.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.enrichPlaylistManifests = enrichPlaylistManifests;
+const node_crypto_1 = require("node:crypto");
+const logger = __importStar(require("../logger"));
+/**
+ * CHAIN_ALIASES translates a DP-1 chain name into the indexer's, outbound.
+ *
+ * DP-1 names the EVM family `evm` (core spec §6: "evm" | "tezos" | "bitmark" |
+ * "other"), because the protocol describes a class of chains. The FF indexer
+ * names the same thing `ethereum`, because it queries a specific one. Without
+ * this every EVM item comes back unresolved, and the failure looks like a
+ * missing artwork rather than a vocabulary mismatch.
+ *
+ * Unlisted values pass through so the indexer, not this table, decides what it
+ * supports.
+ */
+const CHAIN_ALIASES = {
+    evm: 'ethereum',
+};
+/**
+ * `evm` names a family, and this maps it to one member of that family.
+ *
+ * DP-1 core §6 offers "evm" | "tezos" | "bitmark" | "other" and carries no
+ * network identity, while the indexer maps Ethereum, Polygon, Arbitrum,
+ * Optimism, Base, and Zora all back to `evm`. So a DP-1 coordinate cannot say
+ * which EVM network it means, and neither can the response.
+ *
+ * Ethereum is chosen because it is the only EVM network this client can reach:
+ * buildTokenCID maps ethereum to eip155:1 and tezos to tezos:mainnet, and
+ * throws for everything else. A --chain flag would not widen that — it would
+ * only move the throw. The residual risk is narrow and real: an L2 work whose
+ * address and token id also exist on Ethereum would be enriched with the
+ * Ethereum work's metadata, and nothing in the response could reveal it.
+ *
+ * The count is surfaced so the assumption is stated at the point of use rather
+ * than buried here. Widening it belongs upstream, in the indexer client.
+ */
+const AMBIGUOUS_CHAIN = 'evm';
+/**
+ * One CLI invocation stamps one manifest timestamp, matching ref-manifest.ts:
+ * a run that synthesizes several manifests should not write several clocks.
+ */
+const MANIFEST_CREATED = new Date().toISOString();
+/**
+ * canonicalChain collapses both vocabularies onto one name so a coordinate
+ * sent to the indexer and a coordinate read back off its response compare
+ * equal. The direction is deliberately the reverse of CHAIN_ALIASES: this one
+ * is for matching, that one is for querying.
+ */
+function canonicalChain(chain) {
+    const lower = chain.trim().toLowerCase();
+    return lower === 'ethereum' ? 'evm' : lower;
+}
+/**
+ * coordinateKeyOf builds the correlation key for a provenance block, or null
+ * when the block cannot identify a single work.
+ *
+ * The address is lowercased because the indexer echoes it checksummed while
+ * callers typically write it lowercase, and the two must still match.
+ */
+function coordinateKeyOf(provenance) {
+    const contract = provenance?.contract;
+    if (!contract) {
+        return null;
+    }
+    const { chain, address, tokenId } = contract;
+    if (!chain || !address || tokenId === undefined || tokenId === null) {
+        return null;
+    }
+    const token = String(tokenId).trim();
+    if (token.length === 0) {
+        return null;
+    }
+    return `${canonicalChain(chain)}:${address.trim().toLowerCase()}:${token}`;
+}
+/**
+ * describeItem names an item for operator output, preferring its title.
+ */
+function describeItem(item, index) {
+    const title = typeof item.title === 'string' ? item.title.trim() : '';
+    return title.length > 0 ? title : `item ${index + 1}`;
+}
+/**
+ * coordinateFor extracts a lookup key from an item, or null when the item
+ * carries no usable on-chain coordinate.
+ *
+ * All three parts are required. A contract with no token id identifies a
+ * collection rather than a work, and resolving that would attach some other
+ * item's manifest to this one.
+ */
+function coordinateFor(item) {
+    const contract = item.provenance?.contract;
+    if (!contract) {
+        return null;
+    }
+    const { chain, address, tokenId } = contract;
+    if (!chain || !address || tokenId === undefined || tokenId === null) {
+        return null;
+    }
+    const token = String(tokenId).trim();
+    if (token.length === 0) {
+        return null;
+    }
+    const normalized = chain.trim().toLowerCase();
+    return {
+        chain: CHAIN_ALIASES[normalized] ?? normalized,
+        contractAddress: address,
+        tokenId: token,
+    };
+}
+/**
+ * stillFromIndexerSource recovers a thumbnail the manifest builder suppressed.
+ *
+ * `resolveStillUri` blanks a still that equals the source it was given, on the
+ * reasonable ground that pointing a thumbnail at the artwork itself adds
+ * payload and no information. But the source it was given is the one the
+ * INDEXER chose, not the one the curator kept. For a static work the indexer
+ * commonly selects the still as the source, so the thumbnail is dropped —
+ * and when the curator's item points at a live HTML generator instead, the
+ * item ends up with no still at all. That is precisely the case this command
+ * exists to repair: a live work the app cannot rasterize, whose grid tile
+ * stays empty.
+ *
+ * Recovering it is the inverse of the suppression. When the indexer's source
+ * differs from the item's and is an http(s) URL, that source IS the still that
+ * was elided, so it becomes the thumbnail relative to the item's own source.
+ */
+function stillFromIndexerSource(item, resolved) {
+    const indexerSource = typeof resolved.source === 'string' ? resolved.source.trim() : '';
+    const itemSource = typeof item.source === 'string' ? item.source.trim() : '';
+    if (!indexerSource || indexerSource === itemSource) {
+        return '';
+    }
+    if (!indexerSource.startsWith('http://') && !indexerSource.startsWith('https://')) {
+        return '';
+    }
+    // The indexer's source is not necessarily a still. getBestMediaUrl prefers
+    // display.animation_url and media assets over display.image_url, so it is
+    // frequently a live HTML rendition — and writing one into the thumbnail slot
+    // is worse than leaving the slot empty: the grid still cannot rasterize it,
+    // and the item now claims a still it does not have.
+    //
+    // Only a URL that is demonstrably an image is used. The indexer exposes no
+    // separately identified still on the item this command receives, so the file
+    // extension is the evidence available; carrying a real image field through
+    // the batch result would be the better fix and belongs upstream.
+    return looksLikeImage(indexerSource) ? indexerSource : '';
+}
+/**
+ * Media the app can draw a grid tile from, matching the types
+ * playlist-builder.js already recognizes. SVG and video belong here: the app
+ * rasterizes both, and excluding them left works with the empty tile this
+ * command exists to remove. HTML is deliberately absent — an unrasterizable
+ * page in the thumbnail slot is worse than an empty slot, because the item
+ * then claims a still it does not have.
+ */
+const RASTERIZABLE_EXTENSIONS = [
+    '.png',
+    '.jpg',
+    '.jpeg',
+    '.gif',
+    '.webp',
+    '.avif',
+    '.bmp',
+    '.svg',
+    '.mp4',
+    '.webm',
+];
+/**
+ * looksLikeImage tests a URL's path extension, ignoring query and fragment.
+ */
+function looksLikeImage(url) {
+    let pathname = url;
+    try {
+        pathname = new URL(url).pathname;
+    }
+    catch {
+        pathname = url.split('?')[0].split('#')[0];
+    }
+    const lower = pathname.toLowerCase();
+    return RASTERIZABLE_EXTENSIONS.some((extension) => lower.endsWith(extension));
+}
+/**
+ * hasThumbnail reports whether a manifest already carries a default still.
+ */
+function hasThumbnail(manifest) {
+    const thumbnails = manifest.metadata
+        ?.thumbnails;
+    return typeof thumbnails?.default?.uri === 'string' && thumbnails.default.uri.length > 0;
+}
+/**
+ * manifestFor returns the manifest to write onto an item, or undefined when
+ * the indexer resolved the token without building one.
+ *
+ * The curator's own title wins. `item.title` survives enrichment untouched,
+ * but the tombstone reads the manifest first, so attaching an indexer title
+ * that disagrees would change the displayed label while appearing to preserve
+ * it — the indexer writes "Pre-Process #0" where a curator wrote
+ * "Pre-Process". Everything else in the manifest (artist, description,
+ * thumbnails) is what enrichment exists to fetch and is taken as given.
+ */
+function manifestFor(item, resolved) {
+    const still = stillFromIndexerSource(item, resolved);
+    let manifest = resolved.inlineManifest;
+    let rekey = false;
+    if (manifest && still && !hasThumbnail(manifest)) {
+        manifest = {
+            ...manifest,
+            metadata: {
+                ...(manifest.metadata ?? {}),
+                thumbnails: { default: { uri: still } },
+            },
+        };
+        rekey = true;
+    }
+    else if (!manifest && still) {
+        // Nothing was emitted because the still was the only content the token
+        // had, and it had been suppressed. A thumbnail-only manifest is worth its
+        // payload in a way a title-only one is not: it is the difference between
+        // a grid tile and an empty square.
+        const synthesizedTitle = typeof item.title === 'string' ? item.title.trim() : '';
+        manifest = {
+            refVersion: '1.1.0',
+            id: derivedManifestId('', `${synthesizedTitle}\n${still}`),
+            created: MANIFEST_CREATED,
+            locale: 'en',
+            metadata: {
+                ...(synthesizedTitle ? { title: synthesizedTitle } : {}),
+                thumbnails: { default: { uri: still } },
+            },
+        };
+    }
+    if (!manifest) {
+        return undefined;
+    }
+    const metadata = manifest.metadata ?? {};
+    const curatorTitle = typeof item.title === 'string' ? item.title.trim() : '';
+    const overrideTitle = curatorTitle.length > 0 && metadata.title !== curatorTitle;
+    // The id is derived from the finished payload every time, not only when this
+    // command changed something. The indexer keys its id on the token
+    // coordinate, so every rendition of one artwork carries the same id whatever
+    // its content — and under --force the indexer may itself return a different
+    // artist or description under that unchanged id. Deriving from the payload
+    // is the only rule that holds in every case: identical content keeps one
+    // identity, differing content never shares one.
+    //
+    // The original id is folded in, so the result stays anchored to the token
+    // rather than floating free of it, and stays deterministic across runs.
+    //
+    // `rekey` is read only to record that a thumbnail was recovered; the
+    // derivation below covers it either way.
+    void rekey;
+    const finalMetadata = overrideTitle ? { ...metadata, title: curatorTitle } : metadata;
+    return {
+        ...manifest,
+        id: derivedManifestId(typeof manifest.id === 'string' ? manifest.id : '', stableStringify(finalMetadata)),
+        metadata: finalMetadata,
+    };
+}
+/**
+ * stableStringify serializes a value with object keys in sorted order, so the
+ * same content hashes the same however it was assembled.
+ */
+function stableStringify(value) {
+    if (value === null || typeof value !== 'object') {
+        return JSON.stringify(value) ?? 'null';
+    }
+    if (Array.isArray(value)) {
+        return `[${value.map(stableStringify).join(',')}]`;
+    }
+    const entries = Object.entries(value)
+        .filter(([, entryValue]) => entryValue !== undefined)
+        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+        .map(([key, entryValue]) => `${JSON.stringify(key)}:${stableStringify(entryValue)}`);
+    return `{${entries.join(',')}}`;
+}
+/**
+ * derivedManifestId produces a stable id for a manifest whose title this
+ * command replaced, shaped as a UUID so it reads like every other manifest id.
+ */
+function derivedManifestId(originalId, title) {
+    const digest = (0, node_crypto_1.createHash)('sha256').update(`${originalId}\n${title}`).digest('hex');
+    return [
+        digest.slice(0, 8),
+        digest.slice(8, 12),
+        digest.slice(12, 16),
+        digest.slice(16, 20),
+        digest.slice(20, 32),
+    ].join('-');
+}
+/**
+ * enrichPlaylistManifests attaches an inline Ref Manifest to every item that
+ * lacks one and can be resolved on chain.
+ *
+ * The playlist is mutated in place and returned; callers that need the
+ * original should read it twice. Items are looked up in one batch so the
+ * indexer sees a single burst rather than a request per item — warming
+ * previously-unseen tokens is the slow path, and it parallelizes internally.
+ *
+ * Signatures are dropped when anything changed, in both the DP-1 v1.1.0
+ * `signatures[]` form and the legacy flat `signature` this repo still verifies.
+ * A signature covers the document bytes, and an enriched document is a
+ * different document; leaving a stale envelope in place would produce a file
+ * that fails verification at the device with no explanation of why.
+ */
+async function enrichPlaylistManifests(playlist, lookup, options = {}) {
+    const items = Array.isArray(playlist.items) ? playlist.items : [];
+    const skipped = [];
+    const pending = [];
+    // One lookup per distinct artwork, not per item. getNFTTokenInfoBatch runs a
+    // lookup for each token it is handed, and a token the indexer has not seen
+    // triggers an indexing job and a poll that can take minutes. A playlist that
+    // deliberately repeats a work — the same piece at two points in a loop —
+    // would otherwise submit that job once per appearance.
+    const coordinates = new Map();
+    items.forEach((item, index) => {
+        // An item with a `ref` is already labelled, by a manifest this command
+        // cannot see. Ref outranks inlineManifest in the resolution order, so
+        // enriching one writes a manifest the device will ignore while still
+        // invalidating the signature: damage with no visible change.
+        //
+        // --force does not override this. Making the inline manifest win would
+        // mean deleting the curator's `ref` and `refHash`, which is a different
+        // and larger decision than filling in missing metadata — and one that
+        // silently discards the integrity hash the remote manifest is checked
+        // against. If that conversion is ever wanted it should be its own flag,
+        // named for what it does.
+        if (typeof item.ref === 'string' && item.ref.trim().length > 0) {
+            skipped.push({ index, title: describeItem(item, index), reason: 'external-ref' });
+            return;
+        }
+        if (item.inlineManifest && !options.force) {
+            skipped.push({ index, title: describeItem(item, index), reason: 'already-labelled' });
+            return;
+        }
+        const coordinate = coordinateFor(item);
+        const key = coordinateKeyOf(item.provenance);
+        if (!coordinate || !key) {
+            skipped.push({ index, title: describeItem(item, index), reason: 'no-provenance' });
+            return;
+        }
+        // `evm` names a family and the response cannot narrow it, so enriching one
+        // on the assumption of Ethereum can attach a different artwork's artist,
+        // description, and still — into a document the curator then signs. The
+        // operator has to assert the network; the command will not assume it.
+        if (key.startsWith(`${AMBIGUOUS_CHAIN}:`) && !options.assumeEthereum) {
+            skipped.push({ index, title: describeItem(item, index), reason: 'ambiguous-chain' });
+            return;
+        }
+        pending.push({ index, key });
+        if (!coordinates.has(key)) {
+            coordinates.set(key, coordinate);
+        }
+    });
+    const assumedEthereum = [...coordinates.keys()].filter((key) => key.startsWith(`${AMBIGUOUS_CHAIN}:`)).length;
+    if (pending.length === 0) {
+        return { playlist, enriched: 0, skipped, signatureInvalidated: false, assumedEthereum: 0 };
+    }
+    const resolved = await lookup([...coordinates.values()], options.onProgress);
+    // Index what came back by its own coordinate. A response carrying no usable
+    // provenance cannot be attributed to any request, so it is dropped rather
+    // than guessed at; the affected item then reports as not-indexed, which is
+    // exactly what happened.
+    const byCoordinate = new Map();
+    for (const entry of resolved) {
+        const key = coordinateKeyOf(entry.provenance);
+        if (key && !byCoordinate.has(key)) {
+            byCoordinate.set(key, entry);
+        }
+    }
+    let enriched = 0;
+    for (const entry of pending) {
+        const item = items[entry.index];
+        const match = byCoordinate.get(entry.key);
+        const manifest = match ? manifestFor(item, match) : undefined;
+        if (!manifest) {
+            // The indexer resolving a token and the indexer having anything worth
+            // attaching are different outcomes. buildInlineManifestForToken returns
+            // undefined when it has only a title, because a title-only manifest adds
+            // payload to every transfer without adding information. Reporting that
+            // as "the indexer returned nothing" would be false.
+            skipped.push({
+                index: entry.index,
+                title: describeItem(item, entry.index),
+                reason: match ? 'no-metadata' : 'not-indexed',
+            });
+            continue;
+        }
+        item.inlineManifest = manifest;
+        enriched += 1;
+    }
+    const hadSignature = playlist.signatures !== undefined || playlist.signature !== undefined;
+    const signatureInvalidated = enriched > 0 && hadSignature;
+    if (signatureInvalidated) {
+        delete playlist.signatures;
+        delete playlist.signature;
+        logger.debug('[Enrich] Dropped signatures: the enriched document must be re-signed.');
+    }
+    skipped.sort((a, b) => a.index - b.index);
+    return { playlist, enriched, skipped, signatureInvalidated, assumedEthereum };
+}

package/dist/src/utilities/nft-indexer.js

@@ -4,10 +4,19 @@
  * to retrieve comprehensive token information.
  */
 const { PlaylistItemBuilder, ProvenanceBuilder, ContractBuilder } = require('dp1-js');
-// Production by default. INDEXER_API_URL exists so tests can point the
-// client at a local mock, the same way RASTER_API_URL already works — it
-// is not user-facing configuration, which stays removed (initializeIndexer).
-const GRAPHQL_ENDPOINT = process.env.INDEXER_API_URL || 'https://indexer.feralfile.com/graphql';
+// The production endpoint is hardcoded, as PROJECT_SPEC states, and stays
+// that way. INDEXER_API_URL is a test hook, not configuration: the
+// find-command suite spawns the CLI as a child process, so the only way to
+// point it at a local mock is through the environment.
+//
+// It is gated on NODE_ENV=test because index.ts loads dotenv at startup. An
+// ungated read would mean a stray INDEXER_API_URL in someone's .env, or an
+// inherited shell value, silently redirecting every token lookup and indexing
+// mutation — a configuration surface nobody documented and no one would think
+// to check. The gate keeps the hook usable without creating that surface.
+const GRAPHQL_ENDPOINT = process.env.NODE_ENV === 'test' && process.env.INDEXER_API_URL
+    ? process.env.INDEXER_API_URL
+    : 'https://indexer.feralfile.com/graphql';
 const { fetchWithTimeout } = require('./http');
 const logger = require('../logger');
 const { applyTimingToItemBuilder, buildDefaultDisplay } = require('./playlist-builder');

package/docs/EXAMPLES.md

@@ -232,6 +232,44 @@ JSON
 npm run dev -- build /tmp/mixed.json -o playlist-mixed.json -v
 ```
 
+## Enrich an existing playlist
+
+A playlist whose items carry `provenance` but no `inlineManifest` labels
+title-only on the FF1 tombstone, and shows empty tiles in the app for every
+live HTML work. `enrich` repairs it in place.
+
+```bash
+ff-cli enrich playlist.json
+```
+
+```text
+Enrich playlist
+
+  18/18 looked up...
+
+18 of 18 item(s) enriched
+  Output: playlist.json
+```
+
+Items the indexer cannot resolve are listed rather than guessed at:
+
+```text
+Nothing to enrich
+
+  Skipped 2:
+    Kim Asendorf — PXL NET — no provenance.contract chain/address/tokenId to look up
+    Untitled — the indexer returned nothing for it
+```
+
+Enrichment changes the document, so a signed playlist loses its envelope and
+has to be re-signed:
+
+```bash
+ff-cli enrich playlist.json
+ff-cli sign playlist.json
+ff-cli play playlist.json -d "living room"
+```
+
 ## Validate / Sign / Play
 
 ```bash

package/docs/PROJECT_SPEC.md

@@ -197,6 +197,128 @@ nowhere to host a manifest document. Behavior worth knowing downstream:
 - An inline manifest has no `refHash`; its integrity comes from the playlist
   signature.
 
+### Enriching a playlist the CLI did not build
+
+`find` and `build` attach a manifest as they create each item. A playlist that
+arrives another way — assembled by hand, copied out of another document, or
+written before §3.6 existed — has items with a `source` and a `provenance` block
+and nothing else. `enrich` is the repair path for those.
+
+- Enrichment is keyed on `provenance.contract` (chain, address, token id), not
+  on `source`. A source URL is one rendition of a work and several renditions
+  share one; the coordinate is what identifies the artwork.
+- It writes `inlineManifest` and nothing else. `source`, `duration`, `title`,
+  `id`, and `display` are curator decisions and survive untouched even when the
+  indexer disagrees with them.
+- An item the indexer cannot resolve is reported, never synthesized. The same
+  rule the manifest mapping follows applies here: the CLI does not invent fields
+  it cannot substantiate, and an invented artist line inside a signed document
+  is worse than an absent one.
+- DP-1 names the EVM family `evm`; the FF indexer names it `ethereum`. Enrich
+  translates between the two. Unlisted chain names pass through so the indexer
+  decides what it supports.
+- Enrichment changes the document, so both the `signatures[]` envelope and the
+  legacy flat `signature` are removed and the playlist must be re-signed.
+  Leaving a stale envelope in place would produce a file that fails
+  verification at the device with no explanation.
+- An item carrying a `ref` is already labelled by a manifest the CLI cannot
+  see, and `ref` outranks `inlineManifest` in the resolution order, so
+  enrichment skips it. `--force` does not override that: making the inline
+  manifest win would mean deleting the curator's `ref` and `refHash`, which
+  discards the integrity hash the remote manifest is checked against. That
+  conversion, if ever wanted, belongs behind its own flag.
+- Enrichment looks each distinct coordinate up once, however many items share
+  it. A token the indexer has not seen triggers an indexing job and a poll that
+  can take minutes, and a playlist that repeats a work would otherwise submit
+  that job once per appearance.
+- Overriding an item's title changes the manifest's content, so it also changes
+  the manifest's `id`. The indexer derives that id from the token coordinate,
+  so two items of one artwork receive the same one; leaving it alone while
+  changing the title would produce two documents claiming to be the same cached
+  manifest. The replacement is derived from the original id and the title, so
+  it is deterministic across runs.
+- The indexer resolving a token and having something worth attaching are
+  different outcomes: `buildInlineManifestForToken` returns nothing when it has
+  only a title, since a title-only manifest adds payload without adding
+  information. Enrichment reports those separately from tokens it could not
+  resolve at all.
+- A still the manifest builder suppressed is recovered against the item's own
+  source. `resolveStillUri` blanks a thumbnail equal to the source it was
+  handed, which is the source the *indexer* chose; for a static work that is
+  often the still itself. When the curator kept a live HTML source instead, the
+  item would otherwise end up with no thumbnail — the empty grid tile this
+  command exists to remove. When the indexer's source differs from the item's
+  and is http(s) **and is media the app can rasterize**, it is that suppressed
+  still
+  and becomes the thumbnail. The type check matters: `getBestMediaUrl` prefers
+  `display.animation_url` and media assets over `display.image_url`, so the
+  indexer's source is frequently a live HTML rendition, and putting one in the
+  thumbnail slot is worse than leaving it empty — the grid still cannot
+  rasterize it and the item now claims a still it does not have. The predicate
+  matches the media types `playlist-builder.js` already recognizes, images plus
+  SVG and video, and rejects HTML. A
+  thumbnail-only manifest is emitted where none was, unlike a title-only one:
+  it is the difference between a tile and an empty square.
+- `evm` names a family, and enrichment refuses to guess which member. DP-1 §6
+  carries no network identity, and the indexer maps Ethereum, Polygon,
+  Arbitrum, Optimism, Base, and Zora all back to `evm`, so neither the request
+  nor the response can say which network is meant. Ethereum is chosen because
+  it is the only EVM network this client can reach — `buildTokenCID` maps
+  ethereum to `eip155:1` and tezos to `tezos:mainnet` and throws for anything
+  else. The residual risk is narrow: an L2 work whose address and token id also
+  exist on Ethereum would take the Ethereum work's metadata. The command
+  is the operator's to make: `--assume-ethereum` asserts it, and without that
+  flag `evm` items are skipped with a reason that names the flag. The warning
+  prints before anything is written, so an operator who did not mean to assert
+  it still has the file they started with. Reaching an actual L2 belongs in the
+  indexer client, which maps only `ethereum` and `tezos` today.
+- In-place writes refuse to run over an input that changed while the lookup
+  was in flight. The comparison is a hash of the bytes actually parsed, against
+  the resolved write target, so `-o` naming the input by another spelling and a
+  symlink pointing at it are both recognized as the in-place case. It runs
+  immediately before the rename, so the exposed interval is a few syscalls
+  rather than the minutes a lookup takes. It narrows the race and does not
+  close it: compare-then-replace is not atomic against an editor participating
+  in no protocol, and no userspace sequence makes it so. Writing to a distinct
+  `--output` opts out of in-place replacement entirely, which is the right
+  choice when a file is being actively edited.
+- An attached manifest's id is derived from its whole finished metadata block,
+  every time rather than only when this command changed something. The indexer
+  keys its id on the token coordinate, so every rendition of one artwork
+  carries the same id whatever its content, and under `--force` the indexer may
+  itself return a different artist or description under that unchanged id.
+  Deriving from the payload is the only rule that holds in every case:
+  identical content keeps one identity, differing content never shares one. The
+  original id is folded in so the result stays anchored to the token and stays
+  deterministic across runs.
+- In-place writes refuse to run over an input that changed while the lookup
+  was in flight. The lookup can take minutes and the default destination is the
+  input, so a curator's edit or re-sign in that window would otherwise be
+  overwritten by a result computed from older bytes.
+- In-place writes are atomic and crash-durable: the contents are synced before
+  the rename and the containing directory after it, so a power loss cannot
+  leave the destination name pointing at incomplete data. The directory sync is
+  best-effort, since it is not portable.
+- In-place writes are atomic: the candidate goes to a temporary file beside the
+  destination and is renamed over it, so an interruption cannot leave a
+  truncated playlist. A symlinked destination is followed to its target rather
+  than replaced, and the existing file's permission mode is read before the
+  temporary file is created and applied to it before any bytes are written, so
+  a curator-restricted playlist is never briefly world-readable mid-write. The
+  destination's owner and group are carried across too, since a replacement is
+  a new inode and would otherwise take this process's ownership — silently
+  reassigning a shared playlist. Where that cannot be done, the in-place
+  replacement is refused and `--output` is offered instead. Extended ACLs are
+  not preserved, because Node exposes no portable way to read them; a playlist
+  carrying them should be enriched through `--output`.
+- `--output` names a file the caller expects to exist afterwards, so it is
+  written even when nothing was enriched. A no-op without `--output` writes
+  nothing rather than rewriting the input for no gain.
+- The playlist is validated before lookup and the enriched candidate is
+  validated before writing. On either failure the diagnostics are printed and
+  the file is left untouched, rather than replaced with a document that sign,
+  publish, and play would each reject later.
+
 ## Deterministic-first behavior
 
 The CLI is deterministic end to end. There is no natural-language interface; any natural-language layer lives in the user's coding agent, which drives these commands:

package/docs/README.md

@@ -104,6 +104,9 @@ Both paths run the same deterministic pipeline: fetch metadata, assemble a DP-1
   - OpenSea forms: `/assets/ethereum/{contract}/{tokenId}`, `/item/ethereum/{contract}/{tokenId}`, and `/collection/{slug}` (Ethereum collections; the slug is resolved from the public collection page, no API key needed)
   - Verse forms: `/items/ethereum/{contract}/{tokenId}` and `/series/{slug}`
   - Options: `-o, --output <path>`, `-l, --limit <n>`, `-p, --play`, `-d, --device <name>`, `--publish`, `-s, --server <index>`, `-y, --yes`, `--skip-verify`
+- `enrich <file>` – Add missing artist, title, and thumbnail metadata to a playlist that already exists. Resolves each item by its `provenance.contract` and writes an inline Ref Manifest; `source`, `duration`, `title`, and `id` are never touched. Drops the signature when it changes anything, so re-sign afterwards
+  - DP-1 `evm` names a chain family rather than a network, so those items are skipped unless `--assume-ethereum` asserts which one they are. Getting that wrong attaches another artwork's metadata
+  - Options: `-o, --output <file>`, `--force` (replace existing manifests), `--assume-ethereum`, `-v, --verbose`
 - `publish <file>` – Publish a playlist to a feed server (runs `verify` before upload and rejects unsigned or broken playlists)
   - Options: `-s, --server <index>` (server index if multiple configured)
 - `ssh <enable|disable>` – Manage SSH access on an FF1 device
@@ -176,6 +179,41 @@ cat params.json | ff-cli build -o playlist.json
 }
 ```
 
+### Enrich a playlist that came from somewhere else
+
+`find` and `build` label every item they create. A playlist assembled by hand,
+copied from another document, or written before inline manifests existed has no
+`inlineManifest`, and on a device that shows as a tombstone with no artist line
+and an empty tile in the app's grid — the app can draw a thumbnail from an
+image, video, or SVG source, but not from a live HTML work.
+
+`ff-cli enrich` fills that in from the indexer, keyed on each item's
+`provenance.contract`:
+
+```bash
+ff-cli enrich playlist.json --assume-ethereum
+ff-cli enrich playlist.json -o labelled.json
+ff-cli enrich playlist.json --force        # replace existing manifests
+```
+
+`--assume-ethereum` is needed for most playlists. DP-1 records an EVM
+coordinate as `chain: "evm"`, which names Ethereum, Polygon, Arbitrum,
+Optimism, Base and Zora alike, and the indexer's answer collapses back to the
+same word. Enrichment will not pick one for you, because the wrong member
+returns a different artwork's artist and still — into a document you then sign.
+
+It writes `inlineManifest` and nothing else. Items with no
+`provenance.contract` chain, address, and token id cannot be looked up and are
+reported rather than guessed at, and items carrying an external `ref` are left
+alone because `ref` outranks an inline manifest at the device. The playlist is
+validated before and after; on failure the file is left untouched. Enriching
+changes the document, so the signature is removed and the playlist must be
+re-signed before playing:
+
+```bash
+ff-cli enrich playlist.json && ff-cli sign playlist.json
+```
+
 ### Validate, sign, and play
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@feralfile/cli",
-  "version": "2.3.0",
+  "version": "2.4.0",
   "description": "CLI for building, signing, and playing DP-1 playlists of digital art on Feral File devices",
   "repository": {
     "type": "git",