@feralfile/cli 2.2.3 → 2.4.0

package/dist/src/utilities/ref-manifest.js

@@ -0,0 +1,226 @@
+"use strict";
+/**
+ * Inline Ref Manifest construction for DP-1 playlist items.
+ *
+ * DP-1 Playlist Extension §3.6 lets an item carry a complete Ref Manifest
+ * inline instead of behind a `ref` URL. That matters here because ff-cli has
+ * nowhere to host a manifest document: it emits a playlist file and hands it
+ * to an FF1 device. Before dp1-js 2.3.0 there was no item-level home for the
+ * artwork description, artist, or still image the indexer already returns, so
+ * `nft-indexer.js` discarded all three. Inline manifests give them a home.
+ *
+ * This module is a leaf on purpose: it imports only `dp1-js` and the logger,
+ * never another `src/utilities/` module. `nft-indexer.js` already requires
+ * `playlist-builder.js`, so putting this logic in either of them would make
+ * the require graph a question that has to be re-answered on every edit.
+ *
+ * Integrity note: an inline manifest is covered by the playlist signature, so
+ * unlike a ref-fetched manifest it carries no `refHash`. Everything written
+ * here therefore ends up inside a signed document — which is why the mapping
+ * below refuses to synthesize fields the CLI cannot actually substantiate.
+ */
+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.buildInlineManifestForToken = buildInlineManifestForToken;
+const node_crypto_1 = require("node:crypto");
+const dp1_js_1 = require("dp1-js");
+const logger = __importStar(require("../logger"));
+/**
+ * DP-1 version this CLI emits. RefManifestBuilder falls back to "0.1.0" when
+ * `refVersion` is unset, which would contradict the `dpVersion: 1.1.0`
+ * envelope playlist-builder.js builds around these items.
+ */
+const REF_VERSION = '1.1.0';
+/**
+ * The Feral File indexer exposes no language tag on `display`, and the schema
+ * requires a locale. Every string we map comes from that one untagged source,
+ * so "en" is an assumption, not an observation. If the indexer ever returns a
+ * language, thread it through rather than widening this constant.
+ */
+const DEFAULT_LOCALE = 'en';
+/**
+ * One CLI invocation stamps one manifest timestamp.
+ *
+ * Freezing at module load keeps a 500-token `build` from writing 500 different
+ * clocks across items of the same playlist, and keeps two runs byte-diffable
+ * except for this single value. The playlist envelope's own `created` already
+ * varies the same way (playlist-builder.js pins it only under the test-only
+ * deterministicMode). This assumes a short-lived process: do not reuse this
+ * module from a daemon without threading `created` in explicitly.
+ */
+const MANIFEST_CREATED_AT = new Date().toISOString();
+/** Namespace prefix keeping manifest ids from aliasing PlaylistItem ids. */
+const ID_NAMESPACE = 'dp1:ref-manifest:v1';
+/** uuidFromSeed formats a sha256 digest UUID-style, mirroring nft-indexer.js. */
+function uuidFromSeed(seed) {
+    const hash = (0, node_crypto_1.createHash)('sha256').update(seed).digest('hex');
+    return [
+        hash.slice(0, 8),
+        hash.slice(8, 12),
+        hash.slice(12, 16),
+        hash.slice(16, 20),
+        hash.slice(20, 32),
+    ].join('-');
+}
+/** text trims a possibly-absent value down to a non-empty string. */
+function text(value) {
+    return typeof value === 'string' ? value.trim() : '';
+}
+/**
+ * resolveStillUri picks the still image that belongs in `metadata.thumbnails`.
+ *
+ * Returns an empty string unless the candidate is genuinely additional
+ * information. Three rejections, each for a distinct reason:
+ *
+ *   - equal to `sourceUrl`: for a static token `image.url` IS the source
+ *     (see getBestMediaUrl in nft-indexer.js), so a thumbnail identical to it
+ *     is pure duplication inside a signed payload;
+ *   - `data:`: both item factories already refuse data-URI sources, and
+ *     inlining base64 into every playlist would dwarf the playlist itself;
+ *   - anything not http(s): `Thumbnail.uri` carries `format: "uri"`, and an
+ *     `ipfs://` value is not resolvable by the FF1 display path today.
+ */
+function resolveStillUri(token, sourceUrl) {
+    const image = token.image;
+    const candidate = typeof image === 'string' ? text(image) : text(image?.thumbnail) || text(image?.url);
+    if (!candidate || candidate === sourceUrl) {
+        return '';
+    }
+    if (!candidate.startsWith('http://') && !candidate.startsWith('https://')) {
+        return '';
+    }
+    return candidate;
+}
+/**
+ * buildInlineManifestForToken builds the Ref Manifest for one playlist item,
+ * or returns undefined when the token carries nothing worth carrying.
+ *
+ * Emission threshold: at least one of description, artists, or thumbnails must
+ * survive normalization. `title` deliberately does NOT count — it is already a
+ * first-class PlaylistItem field, so a title-only manifest adds payload to
+ * every FF1 transfer and every signed envelope while telling a consumer
+ * nothing new. The threshold is expressed here, once, so the item factories
+ * stay a two-line call and cannot drift apart.
+ *
+ * Deliberately not mapped, each for a reason that should survive future edits:
+ *   - `creditLine`: the schema calls it copyright and credit information. The
+ *     CLI has no such string; deriving one from `token.owner` would assert a
+ *     rights claim it has no basis for, inside a signed document.
+ *   - `tags`: `metadata.attributes` is hard-coded to [] upstream, and NFT
+ *     traits are key/value pairs — flattening them yields garbage like
+ *     ["Blue", "Hat"].
+ *   - `collection`: no Metadata field accepts it, and upstream computes its
+ *     name by splitting the token name on '#' — string surgery, not identity.
+ *   - `owner`: not the artist, not credit, and stale the moment the token
+ *     trades.
+ *   - `controls`: display preferences already live on `item.display`, written
+ *     from the DP-1 §4.1 timing heuristics. Duplicating them here would create
+ *     two sources of truth with no rule for which wins.
+ *   - `i18n`: no localized strings exist anywhere in this pipeline.
+ *
+ * Never throws. A manifest is decoration; nft-indexer.js turns a builder throw
+ * into `{ success: false }`, which the build pipeline counts as a dropped
+ * token — so a malformed thumbnail must not silently shorten a user's
+ * playlist.
+ *
+ * @param token - Token in the internal standard format
+ * @param opts - Resolved item source URL, and an optional created override
+ * @returns A schema-valid RefManifest, or undefined when below the threshold
+ */
+function buildInlineManifestForToken(token, opts = {}) {
+    if (!token || typeof token !== 'object') {
+        return undefined;
+    }
+    const sourceUrl = text(opts.sourceUrl);
+    const title = text(token.name);
+    const description = text(token.description);
+    const artistName = text(token.metadata?.artistName);
+    const stillUri = resolveStillUri(token, sourceUrl);
+    if (!description && !artistName && !stillUri) {
+        return undefined;
+    }
+    try {
+        const metadata = new dp1_js_1.MetadataBuilder();
+        if (title) {
+            metadata.title(title);
+        }
+        if (description) {
+            metadata.description(description);
+        }
+        if (artistName) {
+            metadata.addArtist({ name: artistName });
+        }
+        if (stillUri) {
+            // A plain literal, not ThumbnailBuilder: `w`/`h` became optional in
+            // dp1-js 2.3.0 and we never know the intrinsic pixel dimensions, so the
+            // emitted shape must be exactly { uri } with no undefined-valued keys.
+            metadata.addThumbnail('default', { uri: stillUri });
+        }
+        return new dp1_js_1.RefManifestBuilder()
+            .refVersion(REF_VERSION)
+            .id(manifestId(token, sourceUrl))
+            .created(opts.created ?? MANIFEST_CREATED_AT)
+            .locale(DEFAULT_LOCALE)
+            .metadata(metadata)
+            .build();
+    }
+    catch (error) {
+        logger.debug('[Ref Manifest] Skipping inline manifest:', {
+            contractAddress: token.contractAddress,
+            tokenId: token.tokenId,
+            error: error instanceof Error ? error.message : String(error),
+        });
+        return undefined;
+    }
+}
+/**
+ * manifestId derives a stable id from token coordinates.
+ *
+ * The manifest describes the artwork, not one playlist entry, so the id must
+ * be identical across runs and across playlists — it is a cache key. The
+ * namespace prefix is load-bearing: nft-indexer.js derives the PlaylistItem id
+ * from the bare `${contract}-${tokenId}` string, and a consumer keying a
+ * manifest cache must never alias a playlist-item cache.
+ */
+function manifestId(token, sourceUrl) {
+    const contract = text(token.contractAddress);
+    const tokenId = text(String(token.tokenId ?? ''));
+    if (contract && tokenId) {
+        return uuidFromSeed(`${ID_NAMESPACE}:${text(token.chain)}:${contract}:${tokenId}`);
+    }
+    // Off-indexer tokens (caller-supplied objects) have no coordinates; the
+    // source URL is the only stable identity available.
+    return uuidFromSeed(`${ID_NAMESPACE}:src:${sourceUrl}`);
+}

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
@@ -254,6 +292,10 @@ npm run dev -- play signed.json -d "Living Room Display"
 # Play a hosted DP-1 playlist
 npm run dev -- play "https://cdn.example.com/playlist.json"
 
+# Play a playlist straight from a DP-1 feed server (the URL the feed hands out)
+# Wallet-signed (eip191) documents need --skip-verify until #103 lands
+npm run dev -- play "https://feed.feralfile.com/api/v1/playlists/<slug>" --skip-verify
+
 # Play a media URL directly
 npm run dev -- play "https://example.com/video.mp4"
 

package/docs/PROJECT_SPEC.md

@@ -105,7 +105,7 @@ Based on the code today, the CLI is responsible for:
 - resolving marketplace URLs, on-chain coordinates, and wallet addresses into playlists (`find`)
 - running feed fetches, address queries, contract-based NFT queries, domain resolution, playlist building, verification, publishing, and playback
 - supporting a deterministic build path from structured JSON (`build`)
-- building DP-1 playlist envelopes from NFT metadata or direct media URLs
+- building DP-1 playlist envelopes from NFT metadata or direct media URLs via `dp1-js` document and leaf builders (so constructed playlists stay schema-conformant), including inline Ref Manifests on items that carry indexer metadata
 - validating and verifying playlist structure and signatures
 - signing playlists when a private key is configured
 - publishing validated playlists to configured feed servers
@@ -174,6 +174,151 @@ Today the CLI groups into these workflow areas:
 
 - `ssh enable|disable`
 
+### Inline Ref Manifests
+
+Playlist items carry a full Ref Manifest inline (DP-1 Playlist Extension §3.6)
+rather than behind a `ref` URL, because the CLI emits a playlist file and has
+nowhere to host a manifest document. Behavior worth knowing downstream:
+
+- An item gets a manifest whenever the indexer supplies a description, an
+  artist, or a still image distinct from the item source. A token carrying only
+  a title gets none — the item already has a `title` field, so a title-only
+  manifest would add payload to every device transfer and signed envelope
+  without adding information.
+- Manifest ids are derived from the token's chain, contract, and token id, so
+  they are stable across runs and across playlists — that stable `id` is what
+  identifies the manifest. `created` is frozen once per CLI invocation, so every
+  item in one build shares a single timestamp; it moves between builds, which is
+  expected (see "What determinism does not mean here").
+- Items carry no `ref`. `ref` is a URI to an externally hosted Ref Manifest,
+  and requires `refHash` over HTTPS; a locally built playlist has nowhere to
+  host one, which is the case §3.6 exists to serve. A still image distinct from
+  the source is carried at `inlineManifest.metadata.thumbnails.default.uri`.
+- 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:
@@ -182,6 +327,59 @@ The CLI is deterministic end to end. There is no natural-language interface; any
 - utilities perform the real work and are the source of truth for output correctness
 - invalid or malformed outputs fail validation rather than being passed through
 
+### What determinism does not mean here
+
+It does **not** mean two builds of the same input produce identical bytes or an
+identical signature. Every citation below is from
+[`display-protocol/dp1`](https://github.com/display-protocol/dp1) at core
+v1.1.0, so a reader can check each claim rather than take this section's word
+for it.
+
+**Timestamps are wall-clock, by definition.** The schemas define both creation
+fields as the moment the document was made:
+
+- `core/v1.1.0/schemas/playlist.json` — `created`: *"ISO 8601 timestamp when the
+  playlist was created"*
+- `core/v1.1.0/schemas/ref-manifest.json` — `created`: *"RFC3339 timestamp when
+  the manifest was created"*
+
+Building the same playlist twice creates two documents at two different times,
+so those fields legitimately differ.
+
+**Different bytes therefore mean a different signature, by construction.**
+`core/v1.1.0/spec.md` §7: *"Each signature is computed over the canonical form
+of the entire playlist (excluding the `signature` and `signatures` fields
+themselves)"*, where *"Canonical form ≡ JSON Canonicalization Scheme (JCS), RFC
+8785"*. A differing `created` changes the canonical bytes, which changes the
+payload hash, which changes the signature. That is the signature reporting what
+actually happened — not a defect to engineer away.
+
+**Identity is carried by `id`, not by bytes.**
+`core/v1.1.0/schemas/ref-manifest.json` describes `id` as *"Unique identifier
+for the manifest (for caching)"*, echoed in the envelope example at
+`core/v1.1.0/ref-manifest.md` §3: `"id": "ref-7c3d", // unique identifier (for
+caching)`. Two manifests sharing an `id` are the same manifest. This CLI derives
+manifest ids from token coordinates precisely so identity stays stable while
+timestamps move.
+
+**DP-1 states no reproducible-build requirement.** Searching `core/v1.1.0/spec.md`
+and `core/v1.1.0/ref-manifest.md` for reproducibility language turns up the word
+"deterministic" in exactly two places, neither about build-time byte stability:
+
+- `spec.md` §5, *"Deterministic Reproduction (`repro`)"* — reproducing the
+  **rendering** of code-based artwork, via `engineVersion`, `seed`,
+  `assetsSHA256`, and `frameHash`.
+- `ref-manifest.md` §2 Goals, *"Deterministic merging: predictable behavior
+  across devices and players"* — the **merge order** in §7 (player defaults →
+  playlist defaults → `ref.controls` → runtime overrides).
+
+Neither imposes byte-for-byte stability across builds, and no schema field
+requires `created` to be immutable across regenerations of a document.
+
+`buildDP1Playlist` accepts `deterministicMode` with `fixedTimestamp` and
+`fixedId`. Those exist to pin the envelope for tests and are not used by any
+command.
+
 ## Trust, protocol, and rights assumptions
 
 Important constraints from the broader FF system:

package/docs/README.md

@@ -12,14 +12,6 @@ npm i -g @feralfile/cli
 
 `npm` and `npx` require **Node.js 22 or newer** (see `package.json` `engines`). When a release raises the Node floor, that is a **breaking** change for Node 18/20 users; the GitHub Release for that version should say so explicitly (see `./RELEASING.md` for maintainer guidance).
 
-## Install (curl)
-
-```bash
-curl -fsSL https://feralfile.com/ff-cli-install | bash
-```
-
-Installs a prebuilt bundle for macOS/Linux. Node.js 22 or newer must still be available in `PATH`; the bundle avoids a global npm install, not the Node runtime requirement.
-
 ## Configure
 
 ```bash
@@ -112,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
@@ -184,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
@@ -302,5 +332,5 @@ Setup preserves existing devices when adding new ones. See selection rules and e
 ## Links
 
 - Examples: `./EXAMPLES.md`
-- Release assets: `./RELEASING.md`
+- Releasing: `./RELEASING.md`
 - DP1 spec: `https://github.com/display-protocol/dp1`

package/docs/RELEASING.md

@@ -7,7 +7,7 @@ How releases happen, how to cut one, and what to do when things go sideways.
 1. **Bump `package.json` version** on `main` (or via a `chore: bump version to X.Y.Z` PR — the project has used both patterns).
 2. **Push to `main`** so the tag created in step 3 points at the bump commit.
 3. **Create a GitHub Release** with the tag equal to the version (e.g. tag `1.2.0` → `"version": "1.2.0"`). Use `gh release create 1.2.0 --title "v1.2.0" --notes "..."` or the web UI.
-4. **The `release.yml` workflow fires automatically**, verifies tag == `package.json` version, runs CI, publishes to npm via OIDC, builds binary assets, uploads them to the release, and verifies the package landed on npm.
+4. **The `release.yml` workflow fires automatically**, verifies tag == `package.json` version, runs CI, publishes to npm via OIDC, and verifies the package landed on npm.
 
 That's it. No tokens, no manual `npm publish`. The whole thing takes ~4 minutes end-to-end.
 
@@ -45,35 +45,12 @@ You will probably never do this again for `@feralfile/cli`, but if you ever publ
 ## GitHub Actions workflows
 
 - **`ci.yml`** — formatting, lint, tests, build on Node 22 across ubuntu/macos/windows. Called by `release.yml` and runs on PRs / pushes to `main`.
-- **`build.yml`** — builds prebuilt binaries (macOS/Linux/Windows) and uploads them as workflow artifacts. Triggered manually or from `release.yml`.
-- **`release.yml`** — orchestrates a release. Verifies version, runs CI, publishes to npm (Node 24 + OIDC + provenance), builds binaries, uploads release assets, verifies the package and assets are live. Triggers on published GitHub Releases or manual dispatch (beta only).
+- **`release.yml`** — orchestrates a release. Verifies version, runs CI, publishes to npm (Node 24 + OIDC + provenance), and verifies the package is live. Triggers on published GitHub Releases or manual dispatch (beta only).
 - **`codeql.yml`**, **`dependency-review.yml`** — security scanning.
 
-## Binary release assets
-
-The curl installer (`https://feralfile.com/ff-cli-install`) downloads prebuilt binaries from GitHub Releases. The release workflow builds and uploads them automatically. To build one locally:
-
-**macOS / Linux:**
-
-```bash
-./scripts/release/build-asset.sh
-```
-
-**Windows (PowerShell):**
-
-```powershell
-.\scripts\release\build-asset-windows.ps1
-```
-
-Produces (names vary by OS/arch):
-
-- `release/ff-cli-darwin-arm64.tar.gz` (and `.sha256`) on macOS
-- `release/ff-cli-linux-x64.tar.gz` (and `.sha256`) on Linux
-- `release/ff-cli-windows-x64.zip` (and `.sha256`) on Windows
-
 ## Release notes and breaking changes
 
-GitHub Release text (and any user-facing summary you publish with the version) should state compatibility changes in plain language. **Do not rely on `package.json` `engines` alone**; npm and installers surface it inconsistently, and operators skim release notes first.
+GitHub Release text (and any user-facing summary you publish with the version) should state compatibility changes in plain language. **Do not rely on `package.json` `engines` alone**; npm surfaces it inconsistently, and operators skim release notes first.
 
 ### Node.js engine floor (breaking)
 
@@ -89,22 +66,6 @@ GitHub Release text (and any user-facing summary you publish with the version) s
 
 Later releases only need to repeat this block if the engine floor changes again.
 
-## Installer redirect
-
-`https://feralfile.com/ff-cli-install` should redirect to:
-
-```
-https://raw.githubusercontent.com/feral-file/ff-cli/main/scripts/install.sh
-```
-
-The installer script then fetches the release assets from GitHub Releases.
-
-## Environment overrides
-
-- `FF_CLI_VERSION`: overrides the version label in logs
-- `FF_CLI_NODE_VERSION`: Reserved in script headers for future use; current CI, npm `engines`, and release wrappers assume **Node.js 22+** (required by `dp1-js`).
-- `FF_CLI_OUTPUT_DIR`: output directory (default: `./release`)
-
 ## Troubleshooting
 
 ### `404 Not Found - PUT https://registry.npmjs.org/@feralfile%2fcli`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@feralfile/cli",
-  "version": "2.2.3",
+  "version": "2.4.0",
   "description": "CLI for building, signing, and playing DP-1 playlists of digital art on Feral File devices",
   "repository": {
     "type": "git",
@@ -58,14 +58,14 @@
   "author": "",
   "license": "MIT",
   "dependencies": {
-    "@napi-rs/keyring": "1.3.0",
     "@feralfile/source-resolver": "^1.0.0",
+    "@napi-rs/keyring": "1.3.0",
     "axios": "^1.6.2",
     "bonjour-service": "^1.3.0",
     "chalk": "^4.1.2",
     "commander": "^11.1.0",
     "dotenv": "^16.3.1",
-    "dp1-js": "2.0.0",
+    "dp1-js": "2.3.1",
     "ff1": "^1.0.0",
     "fuzzysort": "^3.1.0",
     "viem": "^2.38.2"