@feralfile/cli 2.2.3 → 2.4.0

package/README.md

@@ -12,15 +12,7 @@ ff-cli is a set of deterministic commands for building DP-1–conformant playlis
 npm i -g @feralfile/cli
 ```
 
-This is the recommended path and the most reliable for the agent workflow — it installs a complete package (including `config.json.example` and the bundled `dp1-js`). Requires Node.js 22+.
-
-## Install (curl)
-
-```bash
-curl -fsSL https://feralfile.com/ff-cli-install | bash
-```
-
-Installs a prebuilt binary for macOS/Linux. Node.js 22+ must still be on your PATH (the bundle runs under `node`). If a command fails right after install, prefer the npm install above.
+This installs a complete package (including `config.json.example` and the bundled `dp1-js`). Requires Node.js 22+.
 
 ## One-off Usage (npx)
 
@@ -138,8 +130,7 @@ Run the same command locally before opening a PR. It checks formatting, lint, te
 
 Other GitHub Actions workflows:
 
-- `.github/workflows/build.yml` builds release assets when called by release automation or manually dispatched.
-- `.github/workflows/release.yml` reuses CI, verifies the release version, publishes npm, uploads assets, and checks the published release.
+- `.github/workflows/release.yml` reuses CI, verifies the release version, publishes to npm, and checks the published package.
 - `.github/workflows/dependency-review.yml` reviews dependency changes on pull requests.
 - `.github/workflows/codeql.yml` runs CodeQL analysis on pull requests and pushes to `main`/`master`.
 

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.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"

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);
+    }
+});