@feralfile/cli 2.10.1 → 4.0.0

package/README.md

@@ -4,7 +4,7 @@ A small Node.js CLI for building DP-1 playlists of digital art.
 
 **Runtime:** Node.js 22 or newer (matches CI and the `dp1-js` dependency). That engine floor is a **breaking** change if you previously used Node 18 or 20—check the **GitHub Release** for the version you move to; release authors follow `docs/RELEASING.md` so the notes stay explicit.
 
-ff-cli is a set of deterministic commands for building DP-1–conformant playlists and playing them on an Art Computer: schema validation, indexing, JSON‑LD, signing, and device delivery. There's no built-in chat — natural language belongs in your coding agent (Claude Code, Codex), which drives ff-cli through the `ff-control` skill (see [Use with Claude Code](#use-with-claude-code)). No LLM API key required.
+ff-cli is a set of deterministic commands for building DP-1–conformant playlists and displaying them on an Art Computer: schema validation, indexing, JSON‑LD, signing, and device delivery. There's no built-in chat — natural language belongs in your coding agent (Claude Code, Codex), which drives ff-cli through the `ff-control` skill (see [Use with Claude Code](#use-with-claude-code)). No LLM API key required.
 
 ## Install
 
@@ -18,15 +18,16 @@ This installs a complete package (including `config.json.example` and the bundle
 
 ```bash
 npx @feralfile/cli setup
-npx @feralfile/cli find https://www.artblocks.io/collection/ringers-by-dmitri-cherniak --play
+npx @feralfile/cli find https://www.artblocks.io/collection/ringers-by-dmitri-cherniak --display
 ```
 
 ## Quick Start
 
 ```bash
 ff-cli setup
-ff-cli find https://objkt.com/tokens/hicetnunc/111068 --play
-ff-cli play "https://example.com/video.mp4" --skip-verify
+ff-cli find https://objkt.com/tokens/hicetnunc/111068 --display
+ff-cli display "https://example.com/video.mp4"
+ff-cli display "https://example.com/"          # any web page
 ```
 
 If you need manual config actions instead of guided setup:
@@ -41,9 +42,9 @@ ff-cli config validate
 `ff-cli setup` is fully scriptable — no TTY required. It runs non-interactively when stdin is not a terminal, or when you pass `-y/--non-interactive`, and takes flags for every step:
 
 ```bash
-# Generate a signing key and register a device in one shot, no prompts
+# Register a device, no prompts. Generates a signing key only when none is configured,
+# and keeps one that is.
 ff-cli setup --non-interactive \
-  --generate-key \
   --device-host http://192.168.1.50:1111 \
   --device-name "Living Room"
 
@@ -51,23 +52,29 @@ ff-cli setup --non-interactive \
 ff-cli setup -y --key "<private-key>" --role agent
 ```
 
+`--generate-key`, `--key`, and `--key-file` refuse to replace a signing key that is already configured, because that key owns the playlists you published. Add `--force` only when you mean to replace it.
+
+Without a terminal, `find` needs `-y` (it displays by default; add `--no-display` to only save). A question with no terminal to answer it exits 1 and names the flag.
+
 Device pairing is also scriptable on its own: `ff-cli device add --host http://<ip>:1111 --name <name>` skips mDNS discovery entirely.
 
+On FF OS with secure control, an FF1 only accepts commands from controllers an owner added. `ff-cli device pair <name>` shows a QR code; an owner scans it with **Add controller** in the Feral File app, and ff-cli enrolls with the role they picked. Pairing needs an internet connection and an FF1 that already has an owner (ff-cli cannot be the first owner); `--resume` finishes a pairing an owner already approved, and `ff-cli device unpair <name>` revokes ff-cli on the FF1 before deleting its keys. FF1s without secure control pair through a one-time code ("Pair with ff-cli" in the app) that hands over relayer access; ff-cli picks the path from the FF1's status, and `--topic-handoff` forces the one-time code. Details: [docs/CONFIGURATION.md](./docs/CONFIGURATION.md#secure-control-pairing).
+
 ## Find an artwork
 
-`ff-cli find` resolves a URL, raw `chain:contract:tokenId`, or a wallet address into a playable DP-1 playlist. The focus is computational and generative art; PFP collections and pre-ERC-721 contracts have limits noted below.
+`ff-cli find` resolves a URL, raw `chain:contract:tokenId`, or a wallet address into a DP-1 playlist ready to display. The focus is computational and generative art; PFP collections and pre-ERC-721 contracts have limits noted below.
 
 ```bash
-# Most satisfying: paste a URL, play it on your FF1
-ff-cli find https://www.artblocks.io/collection/ringers-by-dmitri-cherniak --play
+# Most satisfying: paste a URL, display it on your FF1
+ff-cli find https://www.artblocks.io/collection/ringers-by-dmitri-cherniak --display
 
 # Tezos / hic et nunc via Objkt (the alias resolves to a KT1 contract)
-ff-cli find https://objkt.com/tokens/hicetnunc/111068 --play
+ff-cli find https://objkt.com/tokens/hicetnunc/111068 --display
 
 # Feral File artwork (public id can be hex or numeric — both forms resolve via /api/artworks)
-ff-cli find https://feralfile.com/exhibitions/artwork/f0240e04d64717e319584957f6a83954b029254ad1260b6320472ea8c0c5b1cf --play
+ff-cli find https://feralfile.com/exhibitions/artwork/f0240e04d64717e319584957f6a83954b029254ad1260b6320472ea8c0c5b1cf --display
 
-# Save without playing
+# Save without displaying
 ff-cli find ethereum:0xababababab20053426ad1c782de9ea8444358070:5001410 --output send-receive.json
 ```
 
@@ -75,48 +82,49 @@ Sources: Art Blocks, Objkt, fxhash (canonical `/gentk/...`, live `/iteration/{sl
 
 **Known limitations**
 
-- **CryptoPunks (original)** don't index — the contract predates ERC-721 ([ff-indexer-v2#83](https://github.com/feral-file/ff-indexer-v2/issues/83)).
+- **CryptoPunks (original)** don't index — the contract predates ERC-721 ([ff-indexer-v2#83](https://github.com/feral-file/ff-indexer-v2/issues/83)). The opt-in Raster token source resolves them.
 - **Mainstream PFPs** (Azuki, BAYC, Pudgy Penguins) build a single-item playlist instead of a series — Raster's curation is effectively the series allowlist.
 - **Indexer 502s on burst load** are intermittent ([ff-indexer-v2#82](https://github.com/feral-file/ff-indexer-v2/issues/82)) — retry clears or use `--limit N`.
+- **The Raster token source is opt-in and under evaluation** (`tokenSource: "raster"`). It cannot list a contract, its Feral File metadata is a snapshot (an evolving work displays the version Raster recorded), and some Feral File works point at a retired image host and display black. See [docs/CONFIGURATION.md](docs/CONFIGURATION.md#tokensource).
 
 ## Use with Claude Code
 
 ff-cli ships a [Claude Code](https://docs.claude.com/en/docs/claude-code) skill at `skills/ff-control/SKILL.md`. Install it once:
 
 ```bash
-git clone --depth=1 https://github.com/feral-file/ff-cli /tmp/ff-cli \
-  && mkdir -p ~/.claude/skills \
-  && cp -r /tmp/ff-cli/skills/ff-control ~/.claude/skills/
+d="$(mktemp -d)" && git clone --depth=1 https://github.com/feral-file/ff-cli "$d" \
+  && mkdir -p ~/.claude/skills && cp -r "$d/skills/ff-control" ~/.claude/skills/
 ```
 
-Claude Code will surface it when you ask to build a playlist, play an artwork or URL on an Art Computer, or publish to a feed. The skill validates config, builds, validates the playlist, and sends or publishes — reporting the failing command + exit code if anything breaks. Full prompt and exact flow: [`skills/ff-control/SKILL.md`](./skills/ff-control/SKILL.md).
+Claude Code will surface it when you ask to build a playlist, display an artwork or URL on an Art Computer, or publish to a feed. The skill validates config, builds, validates the playlist, and sends or publishes — reporting the failing command + exit code if anything breaks. Full prompt and exact flow: [`skills/ff-control/SKILL.md`](./skills/ff-control/SKILL.md).
 
 ## Use with Codex
 
 ff-cli ships the same `ff-control` skill in Codex's native skill format. Install it once:
 
 ```bash
-git clone --depth=1 https://github.com/feral-file/ff-cli /tmp/ff-cli \
-  && mkdir -p ~/.codex/skills \
-  && cp -r /tmp/ff-cli/skills/ff-control ~/.codex/skills/
+d="$(mktemp -d)" && git clone --depth=1 https://github.com/feral-file/ff-cli "$d" \
+  && mkdir -p ~/.codex/skills && cp -r "$d/skills/ff-control" ~/.codex/skills/
 ```
 
-Codex will surface it when you ask to build a playlist, play an artwork or URL on an Art Computer, or publish to a feed. The installed skill is `skills/ff-control/SKILL.md`, so the execution flow stays defined in one place. Codex metadata and exact flow: [`skills/ff-control/agents/openai.yaml`](./skills/ff-control/agents/openai.yaml), [`skills/ff-control/SKILL.md`](./skills/ff-control/SKILL.md).
+Codex will surface it when you ask to build a playlist, display an artwork or URL on an Art Computer, or publish to a feed. The installed skill is `skills/ff-control/SKILL.md`, so the execution flow stays defined in one place. Codex metadata and exact flow: [`skills/ff-control/agents/openai.yaml`](./skills/ff-control/agents/openai.yaml), [`skills/ff-control/SKILL.md`](./skills/ff-control/SKILL.md).
 
 ## Dev Quick Start
 
 ```bash
 npm ci
 npm run dev -- setup
-npm run dev -- find https://objkt.com/tokens/hicetnunc/111068 --play
-npm run dev -- play "https://example.com/video.mp4" --skip-verify
+npm run dev -- find https://objkt.com/tokens/hicetnunc/111068 --display
+npm run dev -- display "https://example.com/video.mp4"
 ```
+
 ## Documentation
 
 - Getting started and usage: `./docs/README.md`
 - Configuration: `./docs/CONFIGURATION.md`
 - Examples: `./docs/EXAMPLES.md`
 - SSH access: `ff-cli ssh enable|disable` in `./docs/README.md`
+- Problem reports to Feral File support: `ff-cli report` in `./docs/README.md`
 
 ## Verification
 

package/config.json.example

@@ -7,7 +7,7 @@
   },
   "feedServers": [
     {
-      "baseUrl": "https://dp1-feed-operator-api-prod.autonomy-system.workers.dev/api/v1"
+      "baseUrl": "https://feed.feralfile.com/api/v1"
     },
     {
       "baseUrl": "http://localhost:8787"
@@ -18,6 +18,11 @@
     "role": "curator",
     "curatorName": "YOUR_CURATOR_NAME"
   },
+  "tokenSource": "indexer",
+  "ipfsGateways": {
+    "feralFile": "https://ipfs.feralfile.com/ipfs/",
+    "default": "https://ipfs.filebase.io/ipfs/"
+  },
   "ff1Relayer": {
     "baseUrl": "https://tv-cast-coordination.autonomy-system.workers.dev"
   },

package/dist/index.js

@@ -34,6 +34,9 @@ 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");
+const report_1 = require("./src/commands/report");
+const hidden_alias_help_1 = require("./src/commands/helpers/hidden-alias-help");
+const relay_pairing_channel_1 = require("./src/utilities/control/relay-pairing-channel");
 // Load version from package.json. Try the built location first
 // (dist/index.js -> ../package.json) and fall back to dev (./package.json).
 let packageJsonPath = (0, path_1.resolve)((0, path_1.dirname)(__filename), '..', 'package.json');
@@ -49,13 +52,15 @@ program
     .name('ff-cli')
     .description(packageDescription)
     .version(packageVersion)
-    .addHelpText('after', `\nQuick start:\n  1) ff-cli setup\n  2) ff-cli play <url-or-playlist>\n\nDocs: https://github.com/feral-file/ff-cli\n`);
+    // Lists aliased commands by their name only (`display`, never `display|play`); see hiddenAliasHelp.
+    .configureHelp(hidden_alias_help_1.hiddenAliasHelp)
+    .addHelpText('after', `\nQuick start:\n  1) ff-cli setup\n  2) ff-cli display <url-or-playlist>\n\nDocs: https://github.com/feral-file/ff-cli\n`);
 program.addCommand(setup_1.setupCommand);
 program.addCommand(status_1.statusCommand);
 program.addCommand(validate_1.verifyCommand);
 program.addCommand(validate_1.validateCommand);
 program.addCommand(sign_1.signCommand);
-program.addCommand(play_1.playCommand);
+program.addCommand(play_1.displayCommand);
 program.addCommand(publish_1.publishCommand);
 program.addCommand(unpublish_1.unpublishCommand);
 program.addCommand(fetch_1.fetchCommand);
@@ -65,4 +70,7 @@ program.addCommand(build_1.buildCommand);
 program.addCommand(config_1.configCommand);
 program.addCommand(ssh_1.sshCommand);
 program.addCommand(device_1.deviceCommand);
+program.addCommand(report_1.reportCommand);
+// `device pair` joins its pairing channel on relay v2 when an endpoint is set.
+(0, relay_pairing_channel_1.installRelayPairingChannel)();
 program.parse();

package/dist/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@feralfile/cli",
-    "version": "2.10.1",
-    "description": "CLI for building, signing, and playing DP-1 playlists of digital art on Feral File devices",
+    "version": "4.0.0",
+    "description": "CLI for building, signing, and displaying DP-1 playlists of digital art on Feral File devices",
     "repository": {
         "type": "git",
         "url": "git+https://github.com/feral-file/ff-cli.git"
@@ -68,10 +68,13 @@
         "dp1-js": "2.4.1",
         "ff1": "^1.0.0",
         "fuzzysort": "^3.1.0",
+        "jose": "6.2.12",
+        "qrcode-terminal": "0.12.0",
         "viem": "^2.56.3"
     },
     "devDependencies": {
         "@types/node": "^24.7.1",
+        "@types/qrcode-terminal": "0.12.2",
         "@typescript-eslint/eslint-plugin": "^8.46.0",
         "@typescript-eslint/parser": "^8.46.0",
         "esbuild": "^0.25.10",

package/dist/src/commands/build.js

@@ -8,11 +8,43 @@ const commander_1 = require("commander");
 const chalk_1 = __importDefault(require("chalk"));
 const fs_1 = require("fs");
 const main_1 = require("../main");
+/**
+ * BUILD_PARAMS_HELP documents the params file in `build --help`.
+ *
+ * The schema used to live only in docs/README.md and the agent skill, so a
+ * caller working from `--help` (the first thing an agent reads) had to guess
+ * requirement types. Keep it in step with validateRequirements in src/main.ts.
+ */
+const BUILD_PARAMS_HELP = `
+Params (JSON file, or piped on stdin):
+  {"requirements": [ ...one or more... ], "playlistSettings": { ... }}
+
+Requirement types:
+  query_address       What a wallet owns. ownerAddress (0x… or tz…), optional quantity (number up to 100, or "all").
+                      {"type":"query_address","ownerAddress":"0x…","quantity":5}
+  build_playlist      Tokens from a contract. blockchain ("ethereum" or "tezos"), contractAddress, tokenIds.
+                      {"type":"build_playlist","blockchain":"ethereum","contractAddress":"0x…","tokenIds":["1","2"]}
+  fetch_feed          A feed playlist by title. playlistName, optional quantity.
+                      {"type":"fetch_feed","playlistName":"Unsupervised","quantity":3}
+  feral_file_artwork  One Feral File artwork. artworkId (public id or /exhibitions/artwork/{id} URL).
+
+playlistSettings (all optional):
+  title, durationPerItem (seconds), preserveOrder (default true; false shuffles),
+  deviceName (display on that FF1 after building)
+
+Exit status: 1 when a requirement finds nothing or fails, when named tokenIds
+do not all resolve, or when the send to deviceName fails. The playlist is still
+saved when anything was collected.
+
+Example:
+  echo '{"requirements":[{"type":"query_address","ownerAddress":"0x…","quantity":5}],"playlistSettings":{"title":"My collection"}}' | ff-cli build -o wallet.json
+`;
 exports.buildCommand = new commander_1.Command('build')
     .description('Build playlist from structured parameters (JSON file or stdin)')
     .argument('[params-file]', 'Path to JSON parameters file (or use stdin)')
     .option('-o, --output <filename>', 'Output filename for the playlist', 'playlist.json')
     .option('-v, --verbose', 'Show detailed output', false)
+    .addHelpText('after', BUILD_PARAMS_HELP)
     .action(async (paramsFile, options) => {
     try {
         let params;
@@ -58,6 +90,14 @@ exports.buildCommand = new commander_1.Command('build')
             console.log(chalk_1.default.dim(`  Items: ${result.playlist.items?.length || 0}`));
             console.log(chalk_1.default.dim(`  Output: ${options.output}\n`));
         }
+        const failures = result?.failures ?? [];
+        if (failures.length > 0) {
+            console.error(chalk_1.default.red('Not everything you asked for happened:'));
+            for (const failure of failures) {
+                console.error(chalk_1.default.red(`  ${failure}`));
+            }
+            process.exit(1);
+        }
     }
     catch (error) {
         console.error(chalk_1.default.red('\nError:'), error.message);

package/dist/src/commands/config.js

@@ -26,6 +26,7 @@ exports.configCommand = new commander_1.Command('config')
             const config = (0, config_1.getConfig)();
             console.log(chalk_1.default.blue('\nCurrent configuration\n'));
             console.log(chalk_1.default.bold('Default duration:'), chalk_1.default.white(config.defaultDuration + 's'));
+            console.log(chalk_1.default.bold('Token source:'), chalk_1.default.white((0, config_1.getTokenSourceConfig)().source));
             // The effective list, numbered. `-s <index>` on publish, fetch, replace
             // and unpublish is an index into exactly this list — whichever of
             // config.feedServers, the legacy feed.baseURLs, FEED_BASE_URLS, or the

package/dist/src/commands/device.js

@@ -15,57 +15,71 @@ const device_rename_1 = require("../utilities/device-rename");
 const config_files_1 = require("./helpers/config-files");
 const device_discovery_1 = require("./helpers/device-discovery");
 const prompt_1 = require("./helpers/prompt");
-const ff1_compatibility_1 = require("../utilities/ff1-compatibility");
-const handoff_client_1 = require("../utilities/handoff-client");
-const topic_store_1 = require("../utilities/topic-store");
+const device_control_1 = require("./helpers/device-control");
 const device_removal_1 = require("./helpers/device-removal");
+const http_1 = require("../utilities/http");
+const support_report_1 = require("../utilities/support-report");
+const pairing_1 = require("../utilities/control/pairing");
+/** DEVICE_ID_STATUS_TIMEOUT_MS bounds the status read that names a manually added FF1 at an
+ *  address; a `.local` name gets the longer lanReadTimeoutMs deadline. */
+const DEVICE_ID_STATUS_TIMEOUT_MS = 3_000;
 const deviceCommand = new commander_1.Command('device').description('Manage configured FF1 devices');
 exports.deviceCommand = deviceCommand;
 deviceCommand
     .command('pair')
-    .description('Securely receive relayer access for a configured FF1 from the mobile app')
+    .description('Pair ff-cli with a configured FF1: on secure control, show a code an owner scans with "Add controller" in the Feral File app (needs internet and an owner); otherwise receive relayer access through a one-time code')
+    .argument('[name]', 'Configured device name (uses the default device when omitted)')
+    .option('--label <label>', "Name the owner sees when adding ff-cli (default: this computer's hostname)")
+    .option('--timeout <seconds>', 'How long to wait for an owner, 10-600 (default: 300)')
+    .option('--resume', 'Finish a pairing an owner already approved, without a new code')
+    .option('-y, --yes', 'Move a corrupt controller file aside without asking')
+    .option('--topic-handoff', 'Use the one-time code and "Pair with ff-cli" in the app (FF OS without secure control); chosen automatically when the FF1 reports no secure control')
+    .action(async (name, options) => {
+    await runControlAction('Pairing failed:', () => (0, device_control_1.runPair)(name, options));
+});
+deviceCommand
+    .command('controllers')
+    .description('List the controllers paired with an FF1 (owner only)')
     .argument('[name]', 'Configured device name (uses the default device when omitted)')
     .action(async (name) => {
-    let receiver;
+    await runControlAction('Error:', () => (0, device_control_1.runControllers)(name));
+});
+deviceCommand
+    .command('revoke')
+    .description("Revoke a controller's access to an FF1, or deny its pending request (owner only)")
+    .argument('<controller-id>', 'Controller ID shown by `ff-cli device controllers`')
+    .argument('[name]', 'Configured device name (uses the default device when omitted)')
+    .action(async (ctl, name) => {
+    await runControlAction('Error:', () => (0, device_control_1.runRevoke)(ctl, name));
+});
+deviceCommand
+    .command('unpair')
+    .description("Revoke ff-cli's access on an FF1 (best effort) and delete its controller keys")
+    .argument('[name]', 'Configured device name (uses the default device when omitted)')
+    .option('-y, --yes', 'Delete the keys without asking')
+    .action(async (name, options) => {
+    await runControlAction('Error:', () => (0, device_control_1.runUnpair)(name, options));
+});
+/**
+ * runControlAction runs a pairing/controller action and prints a failure as
+ * an error line plus its follow-up, setting a non-zero exit code.
+ *
+ * @param prefix - Error prefix
+ * @param action - Action to run
+ */
+async function runControlAction(prefix, action) {
     try {
-        const selected = (0, ff1_compatibility_1.resolveConfiguredDevice)(name);
-        if (!selected.success || !selected.device) {
-            throw new Error(selected.error || 'FF1 device is not configured correctly');
-        }
-        const device = selected.device;
-        if (!device.id) {
-            throw new Error(`Device "${device.name || device.host}" has no stable device ID. Re-add it with ff-cli device add before pairing.`);
-        }
-        receiver = await handoff_client_1.TopicHandoffReceiver.create();
-        console.log(chalk_1.default.blue('\nPair ff-cli with Feral File mobile\n'));
-        console.log(`  Device: ${chalk_1.default.bold(device.name || device.id)}`);
-        console.log(`  Device ID: ${chalk_1.default.dim(device.id)}`);
-        console.log("\nIn the mobile app, open this Art Computer's options and choose");
-        console.log(chalk_1.default.bold('“Pair with ff-cli”'), 'then enter:');
-        console.log(`\n  ${chalk_1.default.bold(receiver.shortCode)}\n`);
-        console.log('Before sharing, confirm the mobile security check matches:');
-        console.log(`\n  ${chalk_1.default.bold(receiver.verificationCode)}\n`);
-        console.log(chalk_1.default.dim(`This one-time code expires at ${receiver.expiresAt}. Waiting...`));
-        const payload = await receiver.receiveTopic({ expectedDeviceId: device.id });
-        (0, topic_store_1.storeTopicId)(device.id, payload.topicId);
-        console.log(chalk_1.default.green('\n✓ Relayer access stored in the operating system secure storage.\n'));
+        await action();
     }
     catch (error) {
-        console.error(chalk_1.default.red('\nPairing failed:'), error.message);
-        process.exitCode = 1;
-    }
-    finally {
-        if (receiver) {
-            try {
-                await receiver.close();
-            }
-            catch {
-                // The channel is short-lived and expires automatically. A close
-                // failure must not erase or misreport an already stored credential.
-            }
+        console.error(chalk_1.default.red(`\n${prefix}`), error.message);
+        if (error instanceof device_control_1.CommandFailure && error.details) {
+            console.error(chalk_1.default.dim(error.details));
         }
+        console.error();
+        process.exitCode = 1;
     }
-});
+}
 deviceCommand
     .command('list')
     .description('List all configured FF1 devices')
@@ -120,7 +134,7 @@ deviceCommand
     let prompt = null;
     const ask = async (question) => {
         if (!prompt) {
-            prompt = (0, prompt_1.createPrompt)();
+            prompt = (0, prompt_1.createPrompt)('Pass --host http://<device-ip>:1111 and --name <name> to add or update a device without questions.');
         }
         return prompt.ask(question);
     };
@@ -231,6 +245,37 @@ deviceCommand
                 return;
             }
         }
+        // A manual host has no discovered ID, and pairing needs one: without it
+        // `device pair` sent the user back here, which stored none again. The
+        // LAN status names the device; like an mDNS record it is unauthenticated
+        // and only labels the entry. It never replaces a stored ID: the rows this
+        // update can land on (the matched one, else upsertDevice's same-host or
+        // same-name row) are left alone when one already has an ID, and an ID
+        // another row already holds is not recorded here (that would merge the
+        // two rows or orphan a controller record keyed by the old ID).
+        if (options.host && !discoveredId) {
+            const targets = existingIndex !== -1
+                ? [existingDevices[existingIndex]]
+                : existingDevices.filter((d) => d.host === hostValue || d.name === deviceName);
+            if (!targets.some((d) => d.id)) {
+                const { device: status } = await (0, support_report_1.readDeviceStatus)({ name: deviceName, host: hostValue, apiKey: targets[0]?.apiKey }, (input, init) => (0, http_1.fetchWithTimeout)(input, init ?? {}, (0, pairing_1.lanReadTimeoutMs)(hostValue, DEVICE_ID_STATUS_TIMEOUT_MS)));
+                const statusId = status.device_id?.trim().toUpperCase();
+                const holder = statusId
+                    ? existingDevices.find((d) => !targets.includes(d) && d.id?.trim().toUpperCase() === statusId)
+                    : undefined;
+                if (!statusId || !/^FF1-[A-Z0-9]{4,}$/.test(statusId)) {
+                    console.log(chalk_1.default.dim('Could not read a device ID from the FF1; pairing needs --id FF1-XXXXXXXX.'));
+                }
+                else if (holder) {
+                    console.log(chalk_1.default.yellow(`The FF1 at ${hostValue} reports ${statusId}, which is already configured as "${holder.name || holder.host}". ` +
+                        'Not recording it here: remove that device first, or pass --id.'));
+                }
+                else {
+                    discoveredId = statusId;
+                    console.log(chalk_1.default.dim(`Device ID ${statusId} from the FF1's LAN status.`));
+                }
+            }
+        }
         const result = (0, device_upsert_1.upsertDevice)(existingDevices, { name: deviceName, host: hostValue, id: discoveredId, addresses: discoveredAddresses }, existingIndex !== -1 ? existingIndex : undefined);
         console.log(chalk_1.default.green(`\n${result.updated ? 'Updated' : 'Added'} device: ${deviceName}`));
         config.ff1Devices = { devices: result.devices };

package/dist/src/commands/enrich.js

@@ -18,15 +18,14 @@ const playlist_verifier_1 = require("../utilities/playlist-verifier");
 // distinct output here, and treating it as in-place makes the stale-input guard below refuse a write
 // that was never unsafe. The signer's direct-write path needs the opposite predicate; see same-file.ts.
 const same_file_1 = require("../utilities/same-file");
-// eslint-disable-next-line @typescript-eslint/no-require-imports
-const { resolveTokenBatch } = require('../utilities/nft-indexer');
+const token_source_1 = require("../utilities/token-source");
 /**
  * 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
+ * first. Enrichment runs after a network lookup that can be slow (minutes on
+ * the indexer, which warms unseen 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
@@ -273,7 +272,7 @@ async function syncDirectory(directory, filesystem) {
  *
  * 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.
+ * something sign, publish, and display all reject later, having reported success.
  */
 function reportInvalid(stage, result) {
     console.error(chalk_1.default.red(`\n${stage}`));
@@ -295,10 +294,10 @@ const SKIP_COPY = {
     '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',
+    // The lookup adapter keeps only resolved tokens, so there is no per-item
+    // reason to relay here.
+    'not-indexed': 'the token source returned nothing for it',
+    'no-metadata': 'the token source 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')
@@ -322,7 +321,7 @@ exports.enrichCommand = new commander_1.Command('enrich')
             console.error(chalk_1.default.red('That playlist has no items.'));
             process.exit(1);
         }
-        // Validate before spending minutes on indexer lookups for a document
+        // Validate before spending time on token lookups for a document
         // that was never going to be writable.
         const before = await (0, playlist_verifier_1.validatePlaylist)(playlist);
         if (!before.valid) {
@@ -335,20 +334,16 @@ exports.enrichCommand = new commander_1.Command('enrich')
             printedProgress = true;
             process.stdout.write(chalk_1.default.dim(`\r  ${done}/${count} looked up...`));
         };
-        // resolveTokenBatch 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.
-        //
-        // The raw results are used rather than getNFTTokenInfoBatch's items so
-        // the indexer's still rides beside each item: the item itself drops the
-        // still whenever it equals the indexer's chosen source, and enrichment
+        // Enrichment never sets duration (the curator's timing is not ours to
+        // touch). The raw results are used rather than bare items so the token
+        // source's still rides beside each item: the item itself drops the still
+        // whenever it equals the source the token source chose, and enrichment
         // needs it against the curator's source instead.
+        const source = (0, token_source_1.getTokenSource)();
         const lookup = async (tokens, onProgressCallback) => {
-            const results = await resolveTokenBatch(tokens, undefined, onProgressCallback);
+            const results = await source.resolveTokens(tokens, { onProgress: onProgressCallback });
             return results
-                .filter((result) => result.success && result.item)
+                .filter(token_source_1.isResolved)
                 .map((result) => ({ ...result.item, still: result.still }));
         };
         const result = await (0, enrich_playlist_1.enrichPlaylistManifests)(playlist, lookup, {
@@ -375,7 +370,7 @@ exports.enrichCommand = new commander_1.Command('enrich')
         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.
+            // a malformed manifest from the token source 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);
@@ -409,7 +404,7 @@ exports.enrichCommand = new commander_1.Command('enrich')
         // 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(chalk_1.default.dim(`  Re-sign before displaying: ff-cli sign ${destination}`));
         }
         console.log();
     }