@feralfile/cli 2.7.0 → 2.8.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.8.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/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,35 @@ 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')
     .action(async (file, options) => {
     try {
-        console.log(chalk_1.default.blue('\nPublish playlist\n'));
+        console.log(chalk_1.default.blue(options.replace ? '\nReplace playlist\n' : '\nPublish playlist\n'));
         const { getFeedConfig } = await import('../config.js');
-        const { publishPlaylist } = await import('../utilities/playlist-publisher.js');
+        const { publishPlaylist, replacePlaylist } = 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'));
-            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;
-            }
-            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'));
-                process.exit(1);
+        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));
             }
-            serverUrl = feedConfig.baseURLs[serverIndex];
+            console.log();
+            process.exit(1);
         }
-        const result = await publishPlaylist(file, serverUrl);
+        // 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)
+            : 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 +45,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,22 @@ 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)')
     .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,
+        });
         if (result.success) {
             console.log(chalk_1.default.green('\nPlaylist signed'));
+            // Report the discard explicitly. Dropping an entry is a real change to the document —
+            // someone else's endorsement may have been in it — and staying silent would make a fresh
+            // sign indistinguishable from an appending one.
+            if (result.droppedSignatures > 0) {
+                const plural = result.droppedSignatures === 1 ? '' : 's';
+                console.log(chalk_1.default.dim(`  Replaced ${result.droppedSignatures} existing signature${plural}`));
+            }
             if (Array.isArray(result.playlist?.signatures)) {
                 console.log(chalk_1.default.dim(`  Signatures: ${result.playlist.signatures.length}`));
             }
@@ -31,6 +41,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);
         }
     }

package/dist/src/commands/unpublish.js

@@ -0,0 +1,103 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.unpublishCommand = void 0;
+const commander_1 = require("commander");
+const chalk_1 = __importDefault(require("chalk"));
+const feed_server_1 = require("./helpers/feed-server");
+const prompt_1 = require("./helpers/prompt");
+/**
+ * `ff-cli unpublish <id-or-url>` — delete a playlist this key owns from a feed.
+ *
+ * The delete is irreversible in a way most deletes are not: the feed tombstones the id, so the playlist
+ * cannot be restored and the id can never be reused. Hence the confirmation, which shows the title and
+ * server first, and defaults to no. `-y` skips it for scripts; without a terminal and without `-y` the
+ * command refuses rather than assuming consent.
+ */
+exports.unpublishCommand = new commander_1.Command('unpublish')
+    .description('Delete a playlist from a feed server (signed delete; owner key required)')
+    .argument('<id-or-url>', 'Playlist id, slug, or feed URL')
+    .option('-s, --server <index>', 'Feed server index (use this if multiple servers configured)')
+    .option('-y, --yes', 'Skip the confirmation prompt')
+    .action(async (idOrUrl, options) => {
+    try {
+        console.log(chalk_1.default.blue('\nUnpublish playlist\n'));
+        const { getFeedConfig } = await import('../config.js');
+        const { unpublishPlaylist, fetchPlaylistForUnpublish } = await import('../utilities/playlist-unpublisher.js');
+        const feedConfig = getFeedConfig();
+        const selection = await (0, feed_server_1.selectFeedServer)(feedConfig.baseURLs, {
+            serverArg: options.server,
+            nonInteractive: !!options.yes,
+        });
+        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);
+        }
+        if (!options.yes) {
+            if (!process.stdin.isTTY) {
+                console.error(chalk_1.default.red('\nRefusing to delete without confirmation'));
+                console.log(chalk_1.default.yellow('  This session has no terminal to confirm on. Pass -y to proceed.\n'));
+                process.exit(1);
+            }
+            // Show what is about to go before asking. A bare id says nothing about which playlist it is, and
+            // the answer cannot be taken back. A lookup failure is not fatal here: the delete path repeats
+            // the fetch and reports it properly, so the prompt just falls back to the identifier.
+            let label = idOrUrl;
+            try {
+                const stored = await fetchPlaylistForUnpublish(idOrUrl, selection.url);
+                const title = typeof stored.title === 'string' ? stored.title : '';
+                label = title ? `"${title}" (${stored.id ?? idOrUrl})` : String(stored.id ?? idOrUrl);
+            }
+            catch {
+                label = idOrUrl;
+            }
+            console.log(chalk_1.default.yellow(`  ${label}`));
+            console.log(chalk_1.default.dim(`  Server: ${selection.url}`));
+            console.log(chalk_1.default.dim('  This cannot be undone; the id is tombstoned and cannot be reused.'));
+            console.log();
+            const prompt = (0, prompt_1.createPrompt)();
+            const confirmed = await (0, prompt_1.promptYesNo)(prompt.ask, 'Delete this playlist?', false);
+            prompt.close();
+            console.log();
+            if (!confirmed) {
+                console.log(chalk_1.default.dim('Cancelled.\n'));
+                return;
+            }
+        }
+        const result = await unpublishPlaylist(idOrUrl, selection.url);
+        if (result.success) {
+            console.log(chalk_1.default.green('Unpublished'));
+            if (result.playlistId) {
+                console.log(chalk_1.default.dim(`  Playlist ID: ${result.playlistId}`));
+            }
+            if (result.slug) {
+                console.log(chalk_1.default.dim(`  Slug: ${result.slug}`));
+            }
+            console.log(chalk_1.default.dim(`  Server: ${result.feedServer}`));
+            if (result.message) {
+                console.log(chalk_1.default.dim(`  Status: ${result.message}`));
+            }
+            console.log();
+            return;
+        }
+        console.error(chalk_1.default.red('\nUnpublish failed'));
+        if (result.error) {
+            console.error(chalk_1.default.red(`  ${result.error}`));
+        }
+        if (result.message) {
+            console.log(chalk_1.default.yellow(`\n${result.message}`));
+        }
+        console.log();
+        process.exit(1);
+    }
+    catch (error) {
+        console.error(chalk_1.default.red('\nError:'), error.message);
+        process.exit(1);
+    }
+});