@feralfile/cli 2.10.1 → 4.0.0

package/dist/src/commands/report.js

@@ -0,0 +1,251 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.reportCommand = void 0;
+const commander_1 = require("commander");
+const chalk_1 = __importDefault(require("chalk"));
+const fs_1 = require("fs");
+const config_1 = require("../config");
+const ff1_compatibility_1 = require("../utilities/ff1-compatibility");
+const support_report_1 = require("../utilities/support-report");
+/** REPORT_HELP says what a report carries, so a caller knows what leaves the machine before sending. */
+const REPORT_HELP = `
+The report text comes from --message or --file (not both), or from stdin when
+neither is given and stdin is not a terminal. It goes privately to Feral File
+support with this ff-cli version, the OS, and the Node version, and with
+--email when given. Nothing else leaves this computer: no config, keys, or
+playlists.
+
+With -d, the report also carries the Art Computer's device ID, FF OS version and
+branch, and once it is in, the Art Computer is asked to upload its logs under
+the same reference. It uploads in the background and needs internet. On FF OS
+with secure control, that request needs ff-cli paired with the owner role.
+
+Exit status: 0 when the report reached Feral File support, even if the Art
+Computer did not take the log request; 1 when it did not.
+
+Examples:
+  ff-cli report --message "The work displays black on the Art Computer; in a desktop browser it renders." -d Office
+  ff-cli report --file report.txt --email you@example.com
+  printf '%s\\n' "$REPORT" | ff-cli report -d Office --dry-run
+`;
+/**
+ * `ff-cli report` sends a problem report to Feral File support, the same
+ * pipeline the app's Support & Feedback feeds, so an agent driving ff-cli can
+ * report what went wrong without a person pressing send. The wire contract and
+ * what may be sent live in utilities/support-report.ts.
+ */
+exports.reportCommand = new commander_1.Command('report')
+    .description("Send a problem report to Feral File support, with an Art Computer's logs when one is involved")
+    .option('--message <text>', 'The report text')
+    .option('--file <path>', 'Read the report text from this file')
+    .option('--email <address>', 'Where Feral File support may reply: a bare address, name@example.com')
+    .option('-d, --device <name>', 'The Art Computer involved: adds its device ID, version and branch, and asks it to upload its logs')
+    .option('--dry-run', 'Print the JSON that would be sent, and send nothing')
+    .addHelpText('after', REPORT_HELP)
+    .action(async (options, command) => {
+    try {
+        // The program's own version, so the report carries exactly what
+        // `ff-cli --version` prints (index.ts reads the root package.json).
+        await runReport(options, command.parent?.version() || 'unknown');
+    }
+    catch (error) {
+        console.error(chalk_1.default.red('\nError:'), error.message);
+        process.exit(1);
+    }
+});
+/**
+ * runReport checks the report, reads the Art Computer's status, posts the
+ * report, then asks the Art Computer for its logs. Every refusal before the
+ * post exits 1 with nothing sent; after the post the exit status is 0.
+ *
+ * @param options - Command options
+ * @param ffCliVersion - The version `ff-cli --version` prints
+ * @returns Promise that resolves when the report is done
+ */
+async function runReport(options, ffCliVersion) {
+    const report = await readReport(options);
+    const email = options.email?.trim();
+    checkReport(report, email);
+    const { baseUrl } = (0, config_1.getSupportLogsConfig)();
+    const device = options.device !== undefined ? selectDevice(options.device) : undefined;
+    const deviceBlock = device ? await describeDevice(device) : undefined;
+    // One serialization, so --dry-run prints the very bytes a real run posts.
+    const payload = (0, support_report_1.buildReportPayload)({ report, ffCliVersion, email, device: deviceBlock });
+    const body = JSON.stringify(payload, null, 2);
+    if (options.dryRun) {
+        printDryRun(body, baseUrl, device);
+        return;
+    }
+    const posted = await (0, support_report_1.postReport)(baseUrl, body);
+    if (posted.ok === false) {
+        exitWith(posted);
+    }
+    printReceipt(posted.receipt, email);
+    await askForLogs(device, posted.receipt);
+}
+/**
+ * readReport returns the trimmed report text from exactly one source. Flags
+ * win and stdin is read only when neither is given: an agent's stdin is often
+ * a pipe that carries nothing, and reading it beside a flag would wait on it.
+ *
+ * @param options - Command options
+ * @returns The report text, possibly empty
+ */
+async function readReport(options) {
+    if (options.message !== undefined && options.file !== undefined) {
+        exitWith({ error: 'Give the report once: --message or --file, not both.' });
+    }
+    if (options.message !== undefined) {
+        return options.message.trim();
+    }
+    if (options.file !== undefined) {
+        try {
+            return (await fs_1.promises.readFile(options.file, 'utf-8')).trim();
+        }
+        catch (error) {
+            exitWith({ error: `Could not read --file ${options.file}: ${error.message}` });
+        }
+    }
+    if (process.stdin.isTTY) {
+        exitWith({
+            error: 'No report given.',
+            details: 'Pass --message "<text>" or --file <path>, or pipe the text on stdin.',
+        });
+    }
+    return (await readStdin()).trim();
+}
+/** readStdin reads all of stdin as UTF-8. */
+function readStdin() {
+    return new Promise((resolve, reject) => {
+        let data = '';
+        process.stdin.setEncoding('utf8');
+        process.stdin.on('data', (chunk) => {
+            data += chunk;
+        });
+        process.stdin.on('end', () => resolve(data));
+        process.stdin.on('error', reject);
+    });
+}
+/**
+ * checkReport refuses a report support-logs would refuse, a reply address
+ * that is not one, and a report carrying this computer's signing key.
+ *
+ * @param report - Trimmed report text
+ * @param email - Trimmed --email value; an empty one is refused, not dropped
+ */
+function checkReport(report, email) {
+    if (!report) {
+        exitWith({
+            error: 'The report is empty.',
+            details: 'If the text came from a shell variable, check that it is set.',
+        });
+    }
+    const bytes = Buffer.byteLength(report, 'utf8');
+    if (bytes > support_report_1.MAX_REPORT_BYTES) {
+        exitWith({
+            error: `The report is ${bytes} bytes; Feral File support takes at most ${support_report_1.MAX_REPORT_BYTES}.`,
+            details: "Shorten it. With -d the Art Computer's logs travel separately, so leave log excerpts out.",
+        });
+    }
+    if (email !== undefined && !(0, support_report_1.isBareAddress)(email)) {
+        exitWith({
+            error: `--email "${email}" is not an address Feral File support can reply to.`,
+            details: 'Give a bare ASCII address such as name@example.com, at most 254 characters. ' +
+                "Before the @: 1-64 characters of letters, digits and ! # $ % & ' * + / = ? ^ _ ` { | } ~ -, with single dots only between them. " +
+                'After it: two or more dot-separated labels of letters, digits and hyphens, no label starting or ending with a hyphen. ' +
+                'No display name, angle brackets, quotes, spaces, IP address, underscore in the domain, or non-ASCII characters.',
+        });
+    }
+    if (email !== undefined && (0, support_report_1.isReservedAddress)(email)) {
+        exitWith({
+            error: `--email "${email}" is an address Feral File support does not reply to.`,
+            details: "Support's own address and postmaster or mailer-daemon mailboxes are refused. Give the address where you want the reply, or leave --email out.",
+        });
+    }
+    if ((0, support_report_1.containsSigningKey)(report, (0, config_1.getPlaylistConfig)().privateKey)) {
+        exitWith({
+            error: "The report contains this computer's playlist signing key.",
+            details: 'Remove the key and run the command again. Nothing was sent.',
+        });
+    }
+}
+/** selectDevice resolves -d the way `display -d` does, or exits 1 naming the configured devices. */
+function selectDevice(name) {
+    const selected = (0, ff1_compatibility_1.resolveConfiguredDevice)(name);
+    if (!selected.success || !selected.device) {
+        exitWith({ error: selected.error || 'The Art Computer is not configured correctly.' });
+    }
+    return selected.device;
+}
+/** describeDevice reads the Art Computer block, noting a failed status read without stopping. */
+async function describeDevice(device) {
+    const status = await (0, support_report_1.readDeviceStatus)(device);
+    if (status.error) {
+        console.error(chalk_1.default.yellow(`Could not read the status of ${deviceLabel(device)} (${status.error}); the report goes without its version and branch.`));
+    }
+    return status.device;
+}
+/** printDryRun prints the body on stdout and what a real run would do on stderr. */
+function printDryRun(body, baseUrl, device) {
+    process.stdout.write(`${body}\n`);
+    console.error(chalk_1.default.dim(`Dry run: nothing was sent. A real run posts this to ${baseUrl}/v2/cli/reports`));
+    if (device) {
+        console.error(chalk_1.default.dim(`Then it asks ${deviceLabel(device)} to upload its logs under the reference that comes back.`));
+    }
+}
+/** printReceipt reports the reference in the app's `Support [<id>]` form and who support can reply to. */
+function printReceipt(receipt, email) {
+    console.log(chalk_1.default.green('✓ Report sent to Feral File support'));
+    console.log(`  Reference: Support [${receipt.supportBundleId}]`);
+    console.log(chalk_1.default.dim(email
+        ? `  Support may reply to ${email}`
+        : '  No --email given, so support has no address to reply to'));
+}
+/**
+ * askForLogs asks the Art Computer to upload its logs under the report's
+ * reference and prints the outcome. Best effort: a failure prints a line and
+ * leaves the exit status at 0, since the report already reached support.
+ *
+ * @param device - Art Computer named with -d, if any
+ * @param receipt - The posted report's receipt
+ */
+async function askForLogs(device, receipt) {
+    if (!device) {
+        console.log(chalk_1.default.dim('  No Art Computer named (-d), so no device logs were requested'));
+        return;
+    }
+    const label = deviceLabel(device);
+    if (!receipt.uploadToken) {
+        console.log(chalk_1.default.yellow(`${label} was not asked to upload its logs: support returned no upload token.`));
+        return;
+    }
+    const result = await (0, support_report_1.requestLogUpload)(device, {
+        supportBundleId: receipt.supportBundleId,
+        uploadToken: receipt.uploadToken,
+    });
+    if (result.success) {
+        console.log(chalk_1.default.green(`✓ Asked ${label} to upload its logs under the same reference`));
+        console.log(chalk_1.default.dim('  It uploads in the background and needs internet to do it'));
+        return;
+    }
+    console.log(chalk_1.default.yellow(`${label} did not take the request to upload its logs: ${result.error}`));
+    if (result.details) {
+        console.log(chalk_1.default.dim(`  ${result.details}`));
+    }
+    console.log(chalk_1.default.dim('  The report itself reached support.'));
+}
+/** deviceLabel names a device in output. */
+function deviceLabel(device) {
+    return device.name || device.host;
+}
+/** exitWith prints a failure and exits 1. */
+function exitWith(failure) {
+    console.error(chalk_1.default.red(`\n${failure.error}`));
+    if (failure.details) {
+        console.error(chalk_1.default.dim(`  ${failure.details}`));
+    }
+    process.exit(1);
+}

package/dist/src/commands/setup.js

@@ -17,7 +17,61 @@ const prompt_1 = require("./helpers/prompt");
 const config_placeholders_1 = require("../utilities/config-placeholders");
 const ed25519_key_derive_1 = require("../utilities/ed25519-key-derive");
 const signing_key_source_1 = require("../utilities/signing-key-source");
+const signing_identity_1 = require("../utilities/signing-identity");
 const playlist_signing_role_1 = require("../utilities/playlist-signing-role");
+/**
+ * didKeyOrNull derives the signing identity for key material, or null when the
+ * material does not parse (a placeholder or corrupt value is not an identity
+ * anyone owns playlists with).
+ *
+ * @param {string} keyMaterial - Configured or supplied key material
+ * @returns {string | null} The did:key, or null
+ */
+function didKeyOrNull(keyMaterial) {
+    try {
+        return (0, signing_identity_1.playlistSigningDidKey)(keyMaterial);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * assertKeyReplacementAllowed refuses to replace a configured signing key with
+ * a different one unless the caller passed --force.
+ *
+ * The configured key is the curator identity that owns every playlist it
+ * published: `publish --replace` and `unpublish` only accept that key. setup
+ * keeps no copy of the old key, so replacing it silently is permanent. This
+ * happened in practice: an agent ran the documented `setup --non-interactive
+ * --generate-key` on a machine that was already configured and swapped its
+ * owner key without a word. The interactive "Keep existing signing key?"
+ * question is its own confirmation and does not come through here.
+ *
+ * "Configured" means the identity signing uses today: the config key, or
+ * PLAYLIST_PRIVATE_KEY when config holds none. A config key always wins over
+ * the environment (getPlaylistConfig), so writing one would mask an
+ * environment identity just as surely as overwriting a config key.
+ *
+ * @param {string} currentKey - Effective key material (may be a placeholder or empty)
+ * @param {string} nextKey - Key material setup is about to write
+ * @param {string} flag - The flag that asked for the change, named in the error
+ * @param {boolean} force - Whether --force was passed
+ * @param {string} [source] - Where currentKey came from, when not config.json
+ * @throws {Error} When an existing, different identity would be replaced without --force
+ */
+function assertKeyReplacementAllowed(currentKey, nextKey, flag, force, source) {
+    if (force || (0, config_files_1.isMissingConfigValue)(currentKey)) {
+        return;
+    }
+    const currentDid = didKeyOrNull(currentKey);
+    if (currentDid === null || currentDid === didKeyOrNull(nextKey)) {
+        return;
+    }
+    throw new Error(`A signing key is already configured (${currentDid}${source ? `, from ${source}` : ''}). ` +
+        'It owns the playlists you published; ' +
+        'replacing it means you can no longer replace or unpublish them. ' +
+        `Re-run without ${flag} to keep it, or add --force to replace it.`);
+}
 /** Generate a fresh Ed25519 signing key as base64 PKCS#8 DER (the recommended form). */
 function generateSigningKeyBase64() {
     const keyPair = crypto_1.default.generateKeyPairSync('ed25519');
@@ -28,7 +82,8 @@ exports.setupCommand = new commander_1.Command('setup')
     .option('-y, --non-interactive', 'Run without prompts (for agents/CI); uses flags and safe defaults. Auto-enabled when stdin is not a TTY.')
     .option('--key <privateKey>', 'Signing key material (base64 PKCS#8 DER, 32-byte seed as hex/base64, or PEM)')
     .option('--key-file <path>', 'Read the signing key from this file instead of the command line (preferred for provisioning)')
-    .option('--generate-key', 'Generate a new Ed25519 signing key')
+    .option('--generate-key', 'Generate a new Ed25519 signing key (only when none is configured)')
+    .option('--force', 'Allow --generate-key, --key, or --key-file to replace a configured signing key (it owns your published playlists)')
     .option('--role <role>', `Signing role (${playlist_signing_role_1.DP1_PLAYLIST_SIGNING_ROLES.join(', ')})`)
     .option('--device-host <host>', 'FF1 device host, e.g. http://192.168.1.50:1111 (skips mDNS discovery)')
     .option('--device-name <name>', 'Friendly name for the device')
@@ -84,22 +139,38 @@ exports.setupCommand = new commander_1.Command('setup')
         const currentRole = config.playlist?.role || '';
         let signingKey = currentKey;
         let signingRole = currentRole;
+        // The identity signing uses today. With no usable key in config, signing falls back to
+        // PLAYLIST_PRIVATE_KEY, and a config key written now would silently take its place.
+        const envKey = process.env.PLAYLIST_PRIVATE_KEY?.trim() || '';
+        const keyFromEnv = (0, config_files_1.isMissingConfigValue)(currentKey) && !(0, config_files_1.isMissingConfigValue)(envKey);
+        const effectiveKey = keyFromEnv ? envKey : currentKey;
+        const keySource = keyFromEnv ? 'PLAYLIST_PRIVATE_KEY' : undefined;
+        const force = Boolean(options.force);
         // Already resolved and validated above, before any file was created.
         if (explicitKey !== undefined) {
+            assertKeyReplacementAllowed(effectiveKey, explicitKey.material, explicitKey.flag, force, keySource);
             signingKey = explicitKey.material;
         }
         else if (nonInteractive) {
             // Key precedence with no explicit key: --generate-key, then keep an
             // existing usable key, otherwise generate one so signing works.
-            if (options.generateKey || (0, config_files_1.isMissingConfigValue)(currentKey)) {
-                signingKey = generateSigningKeyBase64();
+            if (options.generateKey || (0, config_files_1.isMissingConfigValue)(effectiveKey)) {
+                const generated = generateSigningKeyBase64();
+                assertKeyReplacementAllowed(effectiveKey, generated, '--generate-key', force, keySource);
+                signingKey = generated;
                 console.log(chalk_1.default.dim('Generated a new Ed25519 signing key.'));
             }
+            else if (keyFromEnv) {
+                console.log(chalk_1.default.dim('Signing with PLAYLIST_PRIVATE_KEY; config.json keeps no key.'));
+            }
         }
         else {
-            if ((0, config_files_1.isMissingConfigValue)(currentKey)) {
+            if ((0, config_files_1.isMissingConfigValue)(effectiveKey)) {
                 signingKey = generateSigningKeyBase64();
             }
+            else if (keyFromEnv) {
+                console.log(chalk_1.default.dim('Signing with PLAYLIST_PRIVATE_KEY; config.json keeps no key.'));
+            }
             else {
                 const ask = getAsk();
                 const keepKey = await (0, prompt_1.promptYesNo)(ask, 'Keep existing signing key?', true);
@@ -109,7 +180,9 @@ exports.setupCommand = new commander_1.Command('setup')
                 }
             }
         }
-        if (signingKey) {
+        // The role applies to whichever identity signs, including PLAYLIST_PRIVATE_KEY when
+        // config keeps no key; skipping it there silently dropped --role.
+        if (signingKey || keyFromEnv) {
             if (nonInteractive) {
                 // Role precedence: --role, then existing role, then 'agent'.
                 try {
@@ -139,7 +212,9 @@ exports.setupCommand = new commander_1.Command('setup')
             }
             config.playlist = {
                 ...(config.playlist || {}),
-                privateKey: signingKey,
+                // With the identity in PLAYLIST_PRIVATE_KEY, keep whatever config held (empty or a
+                // placeholder) so the environment key keeps signing.
+                privateKey: signingKey || (config.playlist?.privateKey ?? ''),
                 role: signingRole,
             };
         }
@@ -243,7 +318,7 @@ exports.setupCommand = new commander_1.Command('setup')
                 console.log(chalk_1.default.yellow('  • Add an FF1 device host'));
             }
         }
-        console.log(chalk_1.default.dim('\nRun: ff-cli play <url-or-playlist>'));
+        console.log(chalk_1.default.dim('\nRun: ff-cli display <url-or-playlist>'));
     }
     catch (error) {
         console.error(chalk_1.default.red('\nSetup failed:'), error.message);

package/dist/src/commands/status.js

@@ -61,7 +61,10 @@ exports.statusCommand = new commander_1.Command('status')
         }
         const configPath = await (0, config_files_1.resolveExistingConfigPath)();
         if (!configPath) {
-            console.log(chalk_1.default.red('config.json not found'));
+            // Name both places looked: when a caller's environment points the user config somewhere
+            // unexpected (a sandboxed HOME with XDG_CONFIG_HOME still set), the path is the clue.
+            const { localPath, userPath } = (0, config_1.getConfigPaths)();
+            console.log(chalk_1.default.red(`config.json not found (looked in ${localPath} and ${userPath})`));
             console.log(chalk_1.default.dim('Run: ff-cli setup'));
             // PLAYLIST_PRIVATE_KEY is a supported signing source on its own, and the did:key it implies is
             // the one value a user must know before they can write a publishable playlist — it has to be