@feralfile/cli 2.7.0 → 2.9.0

package/dist/index.js

@@ -26,6 +26,8 @@ const validate_1 = require("./src/commands/validate");
 const sign_1 = require("./src/commands/sign");
 const play_1 = require("./src/commands/play");
 const publish_1 = require("./src/commands/publish");
+const unpublish_1 = require("./src/commands/unpublish");
+const fetch_1 = require("./src/commands/fetch");
 const find_1 = require("./src/commands/find");
 const build_1 = require("./src/commands/build");
 const enrich_1 = require("./src/commands/enrich");
@@ -55,6 +57,8 @@ program.addCommand(validate_1.validateCommand);
 program.addCommand(sign_1.signCommand);
 program.addCommand(play_1.playCommand);
 program.addCommand(publish_1.publishCommand);
+program.addCommand(unpublish_1.unpublishCommand);
+program.addCommand(fetch_1.fetchCommand);
 program.addCommand(find_1.findCommand);
 program.addCommand(enrich_1.enrichCommand);
 program.addCommand(build_1.buildCommand);

package/dist/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@feralfile/cli",
-    "version": "2.7.0",
+    "version": "2.9.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

@@ -4,6 +4,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.enrichCommand = void 0;
+exports.writePlaylistAtomically = writePlaylistAtomically;
 const commander_1 = require("commander");
 const chalk_1 = __importDefault(require("chalk"));
 const fs_1 = require("fs");
@@ -11,6 +12,12 @@ 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");
+// Rename semantics, not inode identity. This command writes a temp file and renames it over the
+// destination, and rename() replaces a directory ENTRY: onto a hard link it repoints that one name and
+// leaves the input's own name on the untouched original inode. So a hard-link -o is a genuinely
+// 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');
 /**
@@ -28,6 +35,10 @@ const { resolveTokenBatch } = require('../utilities/nft-indexer');
  * 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.
+ *
+ * Exported for tests: whether a destination counts as the input depends on this
+ * function's rename semantics, and pairing it with the wrong predicate is a
+ * mistake that has already been made once.
  */
 async function writePlaylistAtomically(destination, contents, expectedDigest) {
     // Follow a symlink to its target before replacing anything. rename() would
@@ -132,23 +143,6 @@ class OwnershipError extends Error {
         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.
  *
@@ -284,7 +278,7 @@ exports.enrichCommand = new commander_1.Command('enrich')
             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);
+            const replaced = await writePlaylistAtomically(destination, JSON.stringify(result.playlist, null, 2), (await (0, same_file_1.isSameEntryForRename)(destination, file)) ? 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' +

package/dist/src/commands/fetch.js

@@ -0,0 +1,89 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fetchCommand = void 0;
+const commander_1 = require("commander");
+const chalk_1 = __importDefault(require("chalk"));
+const feed_server_1 = require("./helpers/feed-server");
+/**
+ * `ff-cli fetch <id-or-url>` — save a published playlist as the document to edit.
+ *
+ * Editing a published playlist has to start from the stored document: `--replace` requires the `id`,
+ * `slug`, and `created` to equal the stored row's, and rebuilding with `find` or `build` mints new ones.
+ * Nothing in the CLI produced that starting file, so the recovery advice pointed at `verify`, which only
+ * validates and prints a summary — it neither prints nor saves the JSON. That left the documented
+ * edit → re-sign → replace loop starting with a `curl` the CLI could do itself.
+ *
+ * Writing the file is the point, so `-o` is the normal form; without it the document goes to stdout for
+ * piping, and every status line goes to stderr so the two never mix.
+ */
+exports.fetchCommand = new commander_1.Command('fetch')
+    .description('Save a published playlist from a feed server (the starting point for --replace)')
+    .argument('<id-or-url>', 'Playlist id, slug, or feed URL')
+    .option('-s, --server <index>', 'Feed server index (use this if multiple servers configured)')
+    .option('-o, --output <file>', 'Write the playlist here (defaults to stdout)')
+    .action(async (idOrUrl, options) => {
+    try {
+        console.error(chalk_1.default.blue('\nFetch playlist\n'));
+        const { getFeedConfig } = await import('../config.js');
+        const { fetchStoredPlaylist, resolvePlaylistIdentifier } = await import('../utilities/feed-mutation.js');
+        const feedConfig = getFeedConfig();
+        const selection = await (0, feed_server_1.selectFeedServer)(feedConfig.baseURLs, { serverArg: options.server });
+        if (!selection.ok) {
+            console.error(chalk_1.default.red(selection.error));
+            if (selection.detail) {
+                console.error(chalk_1.default.yellow(selection.detail));
+            }
+            console.error();
+            process.exit(1);
+        }
+        const identifier = resolvePlaylistIdentifier(idOrUrl);
+        if (!identifier) {
+            console.error(chalk_1.default.red('No playlist id or URL was given\n'));
+            process.exit(1);
+        }
+        let stored;
+        try {
+            stored = await fetchStoredPlaylist(selection.url, identifier);
+        }
+        catch (error) {
+            const status = error.response?.status;
+            if (status === 404) {
+                console.error(chalk_1.default.red(`\nNo playlist ${identifier} on ${selection.url}`));
+                console.error(chalk_1.default.yellow('  Either the id or slug is wrong for this feed, or the playlist was deleted.\n' +
+                    '  Deleted ids are tombstoned and are never served again.\n'));
+            }
+            else {
+                console.error(chalk_1.default.red('\nFetch failed:'), error.message);
+                console.error();
+            }
+            process.exit(1);
+        }
+        // Two spaces, matching what `sign` and `build` write, so a fetched document and a locally built
+        // one produce the same diff shape when both are edited by hand.
+        const document = `${JSON.stringify(stored, null, 2)}\n`;
+        if (!options.output) {
+            process.stdout.write(document);
+            console.error(chalk_1.default.green('Fetched'));
+            console.error(chalk_1.default.dim(`  Server: ${selection.url}`));
+            console.error();
+            return;
+        }
+        const fs = await import('fs');
+        fs.writeFileSync(options.output, document, 'utf-8');
+        console.error(chalk_1.default.green('Fetched'));
+        console.error(chalk_1.default.dim(`  Playlist ID: ${stored.id ?? identifier}`));
+        if (typeof stored.title === 'string') {
+            console.error(chalk_1.default.dim(`  Title: ${stored.title}`));
+        }
+        console.error(chalk_1.default.dim(`  Server: ${selection.url}`));
+        console.error(chalk_1.default.dim(`  Saved to: ${options.output}`));
+        console.error();
+    }
+    catch (error) {
+        console.error(chalk_1.default.red('\nError:'), error.message);
+        process.exit(1);
+    }
+});

package/dist/src/commands/find.js

@@ -12,6 +12,7 @@ const chalk_1 = __importDefault(require("chalk"));
 const fs_1 = require("fs");
 const source_resolver_1 = require("@feralfile/source-resolver");
 const prompt_1 = require("./helpers/prompt");
+const feed_server_1 = require("./helpers/feed-server");
 const ff_marketplace_1 = require("../utilities/ff-marketplace");
 const objkt_marketplace_1 = require("../utilities/objkt-marketplace");
 const ab_marketplace_1 = require("../utilities/ab-marketplace");
@@ -565,49 +566,21 @@ async function doPublish(savedPath, serverArg, nonInteractive) {
     const { getFeedConfig } = await import('../config.js');
     const { publishPlaylist } = await import('../utilities/playlist-publisher.js');
     const feedConfig = getFeedConfig();
-    if (!feedConfig.baseURLs || feedConfig.baseURLs.length === 0) {
-        console.error(chalk_1.default.red('No feed servers configured.'));
-        console.error(chalk_1.default.yellow('  Add feed server URLs to config.json: feed.baseURLs'));
+    // One implementation of the server rule for every write path (see helpers/feed-server.ts): --server is
+    // validated whatever the server count, and an ambiguous choice fails loudly rather than defaulting.
+    const selection = await (0, feed_server_1.selectFeedServer)(feedConfig.baseURLs, {
+        serverArg,
+        nonInteractive,
+    });
+    if (!selection.ok) {
+        console.error(chalk_1.default.red(selection.error));
+        if (selection.detail) {
+            console.error(selection.detail);
+        }
         process.exitCode = 1;
         return;
     }
-    // Validate --server regardless of server count. parseInt('0abc') would
-    // silently truncate to 0 and route to a different server; with a single
-    // server configured the old code skipped --server validation entirely and
-    // accepted any garbage value while publishing to baseURLs[0].
-    let serverIndex = 0;
-    if (serverArg !== undefined) {
-        const n = Number(serverArg);
-        if (!Number.isInteger(n) || n < 0 || n >= feedConfig.baseURLs.length) {
-            console.error(chalk_1.default.red(`Invalid --server value: ${serverArg} (expected integer in 0..${feedConfig.baseURLs.length - 1})`));
-            process.exitCode = 1;
-            return;
-        }
-        serverIndex = n;
-    }
-    else if (feedConfig.baseURLs.length > 1) {
-        if (nonInteractive) {
-            console.error(chalk_1.default.red(`Multiple feed servers configured (${feedConfig.baseURLs.length}); pass --server <index> when running with --yes.`));
-            process.exitCode = 1;
-            return;
-        }
-        console.log(chalk_1.default.yellow(`Multiple feed servers configured:`));
-        feedConfig.baseURLs.forEach((url, i) => {
-            console.log(chalk_1.default.cyan(`  ${i}: ${url}`));
-        });
-        const prompt = (0, prompt_1.createPrompt)();
-        const answer = await prompt.ask('Select server (0-based index): ');
-        prompt.close();
-        console.log();
-        const n = Number(answer);
-        if (!Number.isInteger(n) || n < 0 || n >= feedConfig.baseURLs.length) {
-            console.error(chalk_1.default.red(`Invalid selection: ${answer} (expected integer in 0..${feedConfig.baseURLs.length - 1})`));
-            process.exitCode = 1;
-            return;
-        }
-        serverIndex = n;
-    }
-    const serverUrl = feedConfig.baseURLs[serverIndex];
+    const serverUrl = selection.url;
     const result = await publishPlaylist(savedPath, serverUrl);
     if (result.success) {
         console.log(chalk_1.default.green('✓ Published'));

package/dist/src/commands/helpers/feed-server.js

@@ -0,0 +1,105 @@
+"use strict";
+/**
+ * Chooses which configured feed server a command writes to.
+ *
+ * The rule this file exists to fix: with more than one server configured and no `--server`, the old
+ * `publish` printed "Select server" and read from stdin. Under a pipe, cron job, or CI step, stdin is
+ * closed, readline resolves immediately with an empty answer, `parseInt('')` yields `NaN`, and the
+ * command exited **0** having published nothing. A silent success is the worst possible answer for a
+ * write, so ambiguity in a non-interactive session is now a non-zero exit that lists the servers.
+ *
+ * Failing rather than defaulting to index 0 is deliberate: the first configured server is usually
+ * production, and a script that meant the other one would otherwise write to the wrong feed and report
+ * success. `find --publish` already answered this way for `--yes`; this generalizes it to any session
+ * with no terminal, and to the delete path, where a wrong-feed write is not undoable.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.selectFeedServer = selectFeedServer;
+exports.describeServers = describeServers;
+const chalk_1 = __importDefault(require("chalk"));
+const prompt_1 = require("./prompt");
+/**
+ * Resolve the feed server URL for a command.
+ *
+ * `--server` is validated whatever the server count: `parseInt('0abc')` truncates to 0 and would route
+ * to a different server than the user named.
+ *
+ * @param baseURLs - Configured feed server base URLs, in config order
+ * @param options - `--server` value and whether the session may prompt
+ * @returns The chosen URL and its index, or the error to report
+ */
+async function selectFeedServer(baseURLs, options = {}) {
+    if (!baseURLs || baseURLs.length === 0) {
+        return {
+            ok: false,
+            error: 'No feed servers configured',
+            detail: 'Add feed server URLs to config.json: feed.baseURLs',
+        };
+    }
+    const upperBound = baseURLs.length - 1;
+    if (options.serverArg !== undefined) {
+        // `Number('')` and `Number('  ')` are both 0, so an empty `--server=` would silently select the
+        // first server — a typo answering as if it were a choice.
+        const raw = options.serverArg.trim();
+        const index = raw.length === 0 ? Number.NaN : Number(raw);
+        if (!Number.isInteger(index) || index < 0 || index >= baseURLs.length) {
+            return {
+                ok: false,
+                error: `Invalid --server value: ${options.serverArg} (expected integer in 0..${upperBound})`,
+                detail: describeServers(baseURLs),
+            };
+        }
+        return { ok: true, url: baseURLs[index], index };
+    }
+    if (baseURLs.length === 1) {
+        return { ok: true, url: baseURLs[0], index: 0 };
+    }
+    if (options.nonInteractive || !process.stdin.isTTY) {
+        return {
+            ok: false,
+            error: `Multiple feed servers configured (${baseURLs.length}); pass --server <index>`,
+            detail: describeServers(baseURLs),
+        };
+    }
+    console.log(chalk_1.default.yellow('Multiple feed servers configured:'));
+    console.log(describeServers(baseURLs));
+    console.log();
+    const answer = await askForSelection(options.ask);
+    console.log();
+    // A bare Enter is not a choice. `Number('')` is 0, so accepting it would send the write to whichever
+    // feed happens to be listed first — usually production — for someone who was hesitating, or who
+    // reflexively took a default that was never offered. This prompt deliberately has no default: the
+    // whole point of asking is that the CLI cannot tell which feed was meant.
+    const selected = answer.trim();
+    const index = selected.length === 0 ? Number.NaN : Number(selected);
+    if (!Number.isInteger(index) || index < 0 || index >= baseURLs.length) {
+        return {
+            ok: false,
+            error: selected.length === 0
+                ? `No server selected (expected integer in 0..${upperBound})`
+                : `Invalid selection: ${selected} (expected integer in 0..${upperBound})`,
+            detail: describeServers(baseURLs),
+        };
+    }
+    return { ok: true, url: baseURLs[index], index };
+}
+/** Ask which server to use, through the injected prompt when a caller supplied one. */
+async function askForSelection(ask) {
+    if (ask) {
+        return ask('Select server (0-based index): ');
+    }
+    const prompt = (0, prompt_1.createPrompt)();
+    try {
+        return await prompt.ask('Select server (0-based index): ');
+    }
+    finally {
+        prompt.close();
+    }
+}
+/** Numbered listing of the configured servers, used in both the prompt and the failure detail. */
+function describeServers(baseURLs) {
+    return baseURLs.map((url, index) => chalk_1.default.cyan(`  ${index}: ${url}`)).join('\n');
+}

package/dist/src/commands/publish.js

@@ -6,47 +6,77 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.publishCommand = void 0;
 const commander_1 = require("commander");
 const chalk_1 = __importDefault(require("chalk"));
-const prompt_1 = require("./helpers/prompt");
+const feed_server_1 = require("./helpers/feed-server");
 exports.publishCommand = new commander_1.Command('publish')
     .description('Publish a playlist to a feed server')
     .argument('<file>', 'Path to the playlist file')
     .option('-s, --server <index>', 'Feed server index (use this if multiple servers configured)')
+    .option('--replace', 'Replace the playlist already stored under this document id, instead of creating a new one')
+    .option('-k, --key <privateKey>', 'Ed25519 private key that signs the replace authorization (overrides config; --replace only)')
     .action(async (file, options) => {
     try {
-        console.log(chalk_1.default.blue('\nPublish playlist\n'));
-        const { getFeedConfig } = await import('../config.js');
-        const { publishPlaylist } = await import('../utilities/playlist-publisher.js');
-        const feedConfig = getFeedConfig();
-        if (!feedConfig.baseURLs || feedConfig.baseURLs.length === 0) {
-            console.error(chalk_1.default.red('\nNo feed servers configured'));
-            console.log(chalk_1.default.yellow('  Add feed server URLs to config.json: feed.baseURLs\n'));
+        // A plain publish signs nothing at request time — it uploads the signatures[] envelope the
+        // document already carries — so --key would do nothing here. Refusing beats accepting it
+        // silently: someone passing a key believes it is being used, and a no-op flag on a command
+        // that writes to a feed is the kind of quiet lie this CLI has been removing.
+        //
+        // Tested for PRESENCE, not truthiness. `--key ""` is what an unset shell variable expands to,
+        // and it is still a key the user meant to supply; skipping the refusal for it published the
+        // document while leaving them believing a key had been checked.
+        if (options.key !== undefined && !options.replace) {
+            console.error(chalk_1.default.red('\n--key has no effect on a plain publish'));
+            console.log(chalk_1.default.yellow('  A publish is authorized by the signatures already inside the document; the command\n' +
+                '  signs nothing. Sign the file first, with the key you meant:\n' +
+                '    ff-cli sign <file> -r curator --key <private key>\n' +
+                '  --key applies to "publish --replace", which signs an authorization intent.\n'));
             process.exit(1);
         }
-        let serverUrl = feedConfig.baseURLs[0];
-        if (feedConfig.baseURLs.length > 1) {
-            if (!options.server) {
-                console.log(chalk_1.default.yellow('Multiple feed servers found. Select one:'));
-                console.log();
-                feedConfig.baseURLs.forEach((url, index) => {
-                    console.log(chalk_1.default.cyan(`  ${index}: ${url}`));
-                });
-                console.log();
-                const prompt = (0, prompt_1.createPrompt)();
-                const selection = await prompt.ask('Select server (0-based index): ');
-                prompt.close();
-                console.log();
-                options.server = selection;
+        console.log(chalk_1.default.blue(options.replace ? '\nReplace playlist\n' : '\nPublish playlist\n'));
+        const { getFeedConfig } = await import('../config.js');
+        const { publishPlaylist, replacePlaylist } = await import('../utilities/playlist-publisher.js');
+        // Validate the signing credential before the server is chosen, for a replace.
+        //
+        // Selecting between several configured feeds is a question put to the operator; asking it and
+        // only then rejecting their key spends their attention on a run that could never have completed.
+        // The credential is already in hand, so it is checked without asking anybody anything.
+        //
+        // Only for --replace: a plain publish signs nothing at request time and must keep working with
+        // no key configured at all, so requiring one here would break it.
+        let replaceKey;
+        if (options.replace) {
+            const { mutationSignerIdentity } = await import('../utilities/feed-mutation.js');
+            try {
+                replaceKey = mutationSignerIdentity(options.key, 'replace').privateKey;
             }
-            const serverIndex = parseInt(options.server || '0', 10);
-            if (isNaN(serverIndex) || serverIndex < 0 || serverIndex >= feedConfig.baseURLs.length) {
-                console.error(chalk_1.default.red('\nInvalid server index'));
+            catch (error) {
+                console.error(chalk_1.default.red('\nCannot sign the replacement'));
+                console.error(chalk_1.default.red(`  ${error.message}`));
+                console.log();
                 process.exit(1);
             }
-            serverUrl = feedConfig.baseURLs[serverIndex];
         }
-        const result = await publishPlaylist(file, serverUrl);
+        const feedConfig = getFeedConfig();
+        const selection = await (0, feed_server_1.selectFeedServer)(feedConfig.baseURLs, { serverArg: options.server });
+        if (!selection.ok) {
+            console.error(chalk_1.default.red(`\n${selection.error}`));
+            if (selection.detail) {
+                console.log(chalk_1.default.yellow(selection.detail));
+            }
+            console.log();
+            process.exit(1);
+        }
+        // A create is never silently upgraded to a replace. They are different writes — a create fails
+        // loudly on a duplicate id, a replace overwrites a published document — and an operator who typed
+        // neither flag meant the safe one.
+        const result = options.replace
+            ? await replacePlaylist(file, selection.url, {
+                // The material resolved above, so the identity validated here is the one that signs.
+                privateKey: replaceKey,
+                keySource: options.key !== undefined ? 'supplied' : 'configured',
+            })
+            : await publishPlaylist(file, selection.url);
         if (result.success) {
-            console.log(chalk_1.default.green('Published'));
+            console.log(chalk_1.default.green(options.replace ? 'Replaced' : 'Published'));
             if (result.playlistId) {
                 console.log(chalk_1.default.dim(`  Playlist ID: ${result.playlistId}`));
             }
@@ -57,7 +87,7 @@ exports.publishCommand = new commander_1.Command('publish')
             console.log();
         }
         else {
-            console.error(chalk_1.default.red('\nPublish failed'));
+            console.error(chalk_1.default.red(options.replace ? '\nReplace failed' : '\nPublish failed'));
             if (result.error) {
                 console.error(chalk_1.default.red(`  ${result.error}`));
             }

package/dist/src/commands/sign.js

@@ -15,12 +15,90 @@ exports.signCommand = new commander_1.Command('sign')
     .option('-k, --key <privateKey>', 'Ed25519 private key in base64 format (overrides config)')
     .option('-r, --role <role>', 'DP-1 signing role (overrides config)')
     .option('-o, --output <file>', 'Output file path (defaults to overwriting input file)')
+    .option('--replace-signatures', 'Discard the existing signatures and sign fresh (use after editing a signed playlist)')
+    .option('--force', 'Overwrite an output file that holds a different document (refused without this)')
     .action(async (file, options) => {
     try {
         console.log(chalk_1.default.blue('\nSign playlist\n'));
-        const result = await signPlaylistFile(file, options.key, options.output, options.role);
+        const result = await signPlaylistFile(file, options.key, options.output, options.role, {
+            replaceSignatures: !!options.replaceSignatures,
+            force: !!options.force,
+        });
         if (result.success) {
             console.log(chalk_1.default.green('\nPlaylist signed'));
+            // Name the casualty. --force overwrote a document this command never read, and the only
+            // record that it existed is now this line.
+            if (result.overwroteAnother) {
+                console.log(chalk_1.default.yellow(`  Overwrote a different document at ${result.outputPath} (--force)`));
+            }
+            // Name every discarded entry, and say only what was actually checked.
+            //
+            // Your own earlier signature is free: this command replaces it. For the rest the only
+            // establishable fact is whether the entry verifies against the document as it stands —
+            // "void" would assert it verified against the PREVIOUS content, which was edited in place
+            // and exists nowhere by the time this runs. A failed verification is equally consistent
+            // with an edit, with a tampered entry, and with one that was never valid, so it is reported
+            // as unverified rather than diagnosed.
+            //
+            // Roles are carried through rather than assumed: a document may hold `agent`,
+            // `institution`, or `licensor` entries, and a `feed` role is not special-cased because any
+            // key can emit one and this CLI has no feed identity to check a kid against.
+            const dropped = result.dropped ?? [];
+            if (dropped.length > 0) {
+                const plural = dropped.length === 1 ? '' : 's';
+                console.log(chalk_1.default.dim(`  Replaced ${dropped.length} existing signature${plural}:`));
+                for (const entry of dropped) {
+                    console.log(chalk_1.default.dim(`    - ${entry.label}`));
+                }
+                // Everything this run did not supersede. A same-key entry in another role belongs here:
+                // the fresh signature asserts a different role, so that entry is gone and not reinstated.
+                const others = dropped.filter((entry) => entry.kind !== 'replaced' && entry.checkable);
+                const stillValid = others.filter((entry) => entry.verified);
+                const unverified = others.filter((entry) => !entry.verified);
+                if (stillValid.length > 0) {
+                    const noun = stillValid.length === 1 ? 'signature' : 'signatures';
+                    const it = stillValid.length === 1 ? 'it' : 'them';
+                    // Say where they still exist. Only two cases reach here: an --output run, where the
+                    // input is untouched and holds them; or an in-place run whose still-valid entries are
+                    // all this key's own in another role, which nobody else has to be asked for. An
+                    // in-place run that would drop another key's still-valid signature never gets this far
+                    // — it is refused, because that file is the only copy and its holder is the only one
+                    // who could make another.
+                    const where = result.inPlace
+                        ? `  ${it.charAt(0).toUpperCase()}${it.slice(1)} ${stillValid.length === 1 ? 'was' : 'were'} made by your own key in another role; sign again to add back any you still want.`
+                        : `  Your input file is untouched, so ${it} ${stillValid.length === 1 ? 'remains' : 'remain'} valid there.`;
+                    console.log(chalk_1.default.yellow(`  ${stillValid.length} other ${noun} still verified over this content and ` +
+                        `${stillValid.length === 1 ? 'was' : 'were'} removed anyway.\n` +
+                        where));
+                }
+                if (unverified.length > 0) {
+                    const noun = unverified.length === 1 ? 'signature' : 'signatures';
+                    // Stated as what was observed, with both explanations, and no instruction that would
+                    // only make sense under one of them.
+                    console.log(chalk_1.default.yellow(`  ${unverified.length} other ${noun} could not be verified against this document:`));
+                    for (const entry of unverified) {
+                        const who = entry.kid ? `...${entry.kid.slice(-8)}` : 'unknown key';
+                        // "claims" is not decoration: an unverified entry carrying this key's kid has not
+                        // established whose it is, and reading it as yours is how a forgery would hide.
+                        const mine = entry.sameKey
+                            ? ' — your own key'
+                            : entry.claimsSigningKey
+                                ? ' — claims your key, unverified'
+                                : '';
+                        console.log(chalk_1.default.yellow(`    ${who}${entry.role ? ` (${entry.role})` : ''}${mine}`));
+                    }
+                    console.log(chalk_1.default.yellow(`  That is consistent with the content having changed since they were made, and\n` +
+                        `  equally with their never having been valid — this command only has the document\n` +
+                        `  as it stands, so it cannot tell which. If you want those signatures on what you\n` +
+                        `  publish, their holders have to sign this document; signing appends, so they can\n` +
+                        `  add to this file without disturbing yours.`));
+                }
+                if (dropped.some((entry) => !entry.checkable)) {
+                    console.log(chalk_1.default.yellow(`  A legacy flat signature carries no kid or role, so nothing here can judge it.`));
+                }
+                // The general fact, never a claim about a specific entry above.
+                console.log(chalk_1.default.dim(`  A feed appends its own signature again after it verifies a replacement.`));
+            }
             if (Array.isArray(result.playlist?.signatures)) {
                 console.log(chalk_1.default.dim(`  Signatures: ${result.playlist.signatures.length}`));
             }
@@ -31,6 +109,17 @@ exports.signCommand = new commander_1.Command('sign')
         }
         else {
             console.error(chalk_1.default.red('\nSign failed:'), result.error);
+            // The one failure whose remedy is not obvious: appending to an edited document can never
+            // verify, because the earlier entries cover bytes that moved. Say so where it happens,
+            // rather than leaving the operator to conclude their key is wrong.
+            if (!options.replaceSignatures &&
+                /verification failed|not verifiable/i.test(String(result.error))) {
+                console.log(chalk_1.default.yellow('\nIf you edited this playlist after it was signed, the existing signatures no longer\n' +
+                    '  cover it, and signing again cannot repair them — signing appends. Sign fresh instead:\n' +
+                    `    ff-cli sign ${file} -r curator --replace-signatures\n` +
+                    '  That discards every existing entry, including any feed signature, and signs the\n' +
+                    '  document as it stands now. It is the path a feed replace expects.'));
+            }
             process.exit(1);
         }
     }