@trawlme/cli 1.19.1 → 1.21.0

package/dist/commands/scraps.js

@@ -5,7 +5,8 @@ import { api, LONG_RUN_TIMEOUT_MS } from '../lib/api.js';
 import { table, json } from '../lib/format.js';
 import { promptPassword } from '../lib/prompt.js';
 import { validateObjectId } from '../lib/validate.js';
-import { classifyError, reportError, UsageError } from '../lib/errors.js';
+import { classifyError, reportError, UsageError, RefusalError } from '../lib/errors.js';
+import { confirmDestructive, isInteractive } from '../lib/confirm.js';
 import { formatDoctor, formatAutofix, fetchRunAndFix, pickRun, pickFix } from './doctor.js';
 import { renderPinch, pinchEnabled } from '../lib/pinch.js';
 /**
@@ -66,12 +67,21 @@ function statusIcon(status) {
     return chalk.dim('—');
 }
 export const scraps = new Command('scraps').description('Manage scraps');
-// shared SSE streaming helper
-async function watchActivities(id) {
-    console.log(chalk.dim('Streaming activities (Ctrl+C to stop)…\n'));
+// shared SSE streaming helper. `asJson` (#107) emits one raw JSON object per
+// line (NDJSON) on stdout instead of the human-formatted timestamped text —
+// a streaming command still needs a pure-stdout machine mode, just line-
+// delimited instead of a single blob (there's no single "final" payload to
+// wait for).
+async function watchActivities(id, asJson) {
+    if (!asJson)
+        console.log(chalk.dim('Streaming activities (Ctrl+C to stop)…\n'));
     for await (const event of api.stream(`/api/scraps/${id}/activities/stream`)) {
         try {
             const activity = JSON.parse(event);
+            if (asJson) {
+                console.log(JSON.stringify(activity));
+                continue;
+            }
             const time = new Date(activity.createdAt).toLocaleTimeString();
             console.log(`${chalk.dim(`[${time}]`)} ${activity.message}`);
         }
@@ -121,6 +131,14 @@ const POLL_INTERVAL_MS = 2000;
 // Mirrors LONG_RUN_TIMEOUT_MS (#91 item 1) — the server-side worst case this
 // polls for is the same one that timeout was sized for.
 const POLL_TIMEOUT_MS = LONG_RUN_TIMEOUT_MS;
+// #107 review F1 — a genuinely unreachable API must not run the watch
+// silently for the full 300s timeout with dead air; after this many
+// CONSECUTIVE (not cumulative — any successful poll resets the counter)
+// failed polls, treat it as a persistent error and surface it immediately
+// instead of waiting out the clock. At the default 2s interval this gives up
+// after ~10s of continuous failures — comfortably longer than any single
+// transient blip, nowhere near the 300s ceiling.
+const MAX_CONSECUTIVE_POLL_ERRORS = 5;
 /**
  * #91 P1 — replaces "await the run to completion, THEN open the activities
  * SSE stream" (which showed NOTHING: the activities SSE
@@ -182,10 +200,37 @@ const POLL_TIMEOUT_MS = LONG_RUN_TIMEOUT_MS;
  * this function has, so it resolves to the same honest timeout rather than
  * risk reporting a possibly-wrong outcome (never a lie, at worst a timeout
  * telling the caller to check `doctor`).
+ *
+ * #107 review F1 — before this fix, `run|trigger --json --watch` was
+ * outcome-blind: `quiet` suppressed ALL output (including "Run finished:
+ * failure" and the timeout notice), a transient poll error was caught and
+ * silently retried FOREVER within the deadline, and the process always
+ * exited 0 after the poll loop regardless of what the watched run actually
+ * did — dead air, then a clean exit code, even for a failed or timed-out
+ * run. An agent scripting this CLI had no way to tell success from failure
+ * from "we gave up". Fixed by:
+ *  - emitting exactly ONE final NDJSON line on stdout under `--json` once
+ *    the watch reaches ANY of its three exits (terminal status, timeout, or
+ *    a persistent poll error) — `{runId,status}` (+`error` for a poll
+ *    error) — while every intermediate progress line stays suppressed
+ *    (unchanged from before);
+ *  - setting `process.exitCode` non-zero on a genuine run failure, a
+ *    timeout, or a persistent poll error, and `0` on a real success — in
+ *    BOTH `--json` and human `--watch` modes (human mode used to exit 0
+ *    unconditionally, the same bug, just silent instead of dishonest);
+ *  - giving up after `MAX_CONSECUTIVE_POLL_ERRORS` consecutive failed reads
+ *    instead of retrying the same dead endpoint for the full 300s.
  */
 export async function pollRunProgress(id, before, opts = {}) {
     const intervalMs = opts.intervalMs ?? POLL_INTERVAL_MS;
     const timeoutMs = opts.timeoutMs ?? POLL_TIMEOUT_MS;
+    // #107 — `run --json --watch` / `trigger --json --watch` must keep stdout
+    // pure JSON: none of this function's intermediate progress text is safe to
+    // print once a caller asked for --json. `asJson` suppresses every
+    // intermediate console.log below (including the pinch celebration frame)
+    // while the polling/wait logic itself runs unchanged; the ONE exception is
+    // the single final outcome line emitted right before each return below.
+    const asJson = opts.json ?? false;
     let beforeId = before?.id;
     let beforeAlreadyInFlight = before?.alreadyInFlight ?? false;
     // #97 — only an EXPLICIT captured:false (capture's GET actually threw)
@@ -193,10 +238,13 @@ export async function pollRunProgress(id, before, opts = {}) {
     // capture entirely) or `captured` being true/absent both mean "trust
     // beforeId as given", preserving every existing call site's behavior.
     let baselineEstablished = before?.captured ?? true;
-    console.log(chalk.dim('Live activity streaming has no signal for this run (async/cross-pod) — polling for progress instead…\n'));
+    if (!asJson) {
+        console.log(chalk.dim('Live activity streaming has no signal for this run (async/cross-pod) — polling for progress instead…\n'));
+    }
     const deadline = Date.now() + timeoutMs;
     const seen = new Set();
     let first = true;
+    let consecutivePollErrors = 0;
     while (Date.now() < deadline) {
         if (!first)
             await sleep(intervalMs);
@@ -204,9 +252,28 @@ export async function pollRunProgress(id, before, opts = {}) {
         let scrap;
         try {
             scrap = await api.get(`/api/scraps/${id}`);
+            consecutivePollErrors = 0;
         }
-        catch {
-            continue; // transient — keep polling rather than aborting the wait
+        catch (err) {
+            consecutivePollErrors++;
+            // #107 review F1 — a single failed read is still a TRANSIENT blip,
+            // safe to retry within the deadline (unchanged). Only once reads fail
+            // this many times IN A ROW is the API treated as genuinely
+            // unreachable — surface that honestly instead of quietly burning the
+            // full 300s timeout on a dead endpoint.
+            if (consecutivePollErrors >= MAX_CONSECUTIVE_POLL_ERRORS) {
+                const message = err instanceof Error ? err.message : String(err);
+                if (asJson) {
+                    const outcome = { runId: beforeId, status: 'poll_error', error: message };
+                    console.log(JSON.stringify(outcome));
+                }
+                else {
+                    console.log(chalk.red(`✗ Polling failed repeatedly (${message}) — check status with: trawl scraps doctor ${id}`));
+                }
+                process.exitCode = 1;
+                return;
+            }
+            continue;
         }
         const last = scrap.history?.[0];
         if (!last?._id)
@@ -233,6 +300,8 @@ export async function pollRunProgress(id, before, opts = {}) {
                 if (seen.has(key))
                     continue;
                 seen.add(key);
+                if (asJson)
+                    continue;
                 const time = new Date(a.createdAt).toLocaleTimeString();
                 console.log(`${chalk.dim(`[${time}]`)} ${a.message}`);
             }
@@ -242,19 +311,42 @@ export async function pollRunProgress(id, before, opts = {}) {
         }
         if (last.status !== null) {
             const outcome = last.statusDetail ?? (last.status ? 'success' : 'failure');
-            console.log(chalk.dim(`Run finished: ${outcome}`));
-            // Pinch celebrates a clean run finish (#94) — mirrors doctor.ts's own
-            // `status === true` success definition (regardless of statusDetail),
-            // never for a failed/regression run. Neither `run --watch` nor
-            // `trigger --watch` (the only two callers) has a --json flag, so this
-            // is always safe to print. Guarded by pinchEnabled() (NO_COLOR/non-TTY).
-            if (last.status === true && pinchEnabled()) {
-                console.log(renderPinch('celebrating'));
+            // #107 review F1 — the exit code, in BOTH modes: a regression row's
+            // WRITE actually succeeded (see lastStatus()'s own #91 comment above,
+            // and `scraps data`'s isRegression branch) and an 'empty' row is a
+            // genuine zero-item success — neither is a real failure. Only
+            // status:false with neither of those details (e.g. 'error', or no
+            // detail at all) is a genuine failed run.
+            const isGenuineFailure = last.status === false && outcome !== 'empty' && outcome !== 'regression';
+            if (asJson) {
+                const payload = { runId: last._id, status: outcome };
+                console.log(JSON.stringify(payload));
+            }
+            else {
+                console.log(chalk.dim(`Run finished: ${outcome}`));
+                // Pinch celebrates a clean run finish (#94) — mirrors doctor.ts's own
+                // `status === true` success definition (regardless of statusDetail),
+                // never for a failed/regression run. Guarded by pinchEnabled()
+                // (NO_COLOR/non-TTY) and never under --json (stdout must stay pure).
+                if (last.status === true && pinchEnabled()) {
+                    console.log(renderPinch('celebrating'));
+                }
             }
+            process.exitCode = isGenuineFailure ? 1 : 0;
             return;
         }
     }
-    console.log(chalk.yellow(`⚠ Timed out waiting for the run to finish — check status with: trawl scraps doctor ${id}`));
+    // #107 review F1 — timeout: honest non-zero exit in both modes, plus the
+    // machine-readable final line under --json (never silently exit 0 after a
+    // watch that never actually confirmed what happened).
+    if (asJson) {
+        const outcome = { runId: beforeId, status: 'timeout' };
+        console.log(JSON.stringify(outcome));
+    }
+    else {
+        console.log(chalk.yellow(`⚠ Timed out waiting for the run to finish — check status with: trawl scraps doctor ${id}`));
+    }
+    process.exitCode = 1;
 }
 // list
 scraps
@@ -441,11 +533,17 @@ function withTierUnconfirmed(data, tierWasRequested) {
 }
 /** #86 finding 5 — the standard error envelope for a refused tier override,
  * routed through the same reportError() central formatting path used
- * everywhere else (exit 1: a business-logic refusal, not a usage error). */
+ * everywhere else (exit 1: a business-logic refusal, not a usage error).
+ *
+ * #107 review F3 — uses `RefusalError` (kind:"refused"), not a bare `Error`
+ * (which fell through classifyError's default `kind:"unknown"` bucket,
+ * indistinguishable from a generic crash even though the README sells `kind`
+ * as the machine discriminant an agent branches on).
+ */
 function reportTierRefusal(data, wantsJson) {
     const ov = data._tierOverride;
     const message = `Tier ceiling override refused: ${ov?.reason ?? 'unknown'} (requested ${ov?.requestedMaxTier ?? '—'}; kept the registry cap)`;
-    return reportError(new Error(message), { json: wantsJson });
+    return reportError(new RefusalError(message), { json: wantsJson });
 }
 // create
 scraps
@@ -616,6 +714,7 @@ scraps
     .command('run <id>')
     .description('Run a scrap')
     .option('-w, --watch', 'Show progress after launching (polls — see `trawl scraps trigger --watch`, #91)')
+    .option('--json', 'Output the raw launch payload as JSON')
     .action(async (id, opts) => {
     validateObjectId(id);
     // #91 P1 / #93 item 1 — captured BEFORE launching so pollRunProgress can
@@ -624,12 +723,22 @@ scraps
     const beforeRun = opts.watch ? await captureBeforeRunState(id) : undefined;
     // #91 P0 — GET /api/scraps/load/:id runs the scrap synchronously
     // server-side (30-250s); the 30s default was aborting it mid-flight.
-    await oraPromise(() => api.get(`/api/scraps/load/${id}`, { timeoutMs: LONG_RUN_TIMEOUT_MS }), {
-        text: 'Launching scrap…',
-        successText: 'Scrap launched',
-    });
+    const call = () => api.get(`/api/scraps/load/${id}`, { timeoutMs: LONG_RUN_TIMEOUT_MS });
+    // #107 — under --json the stdout path stays pure: no spinner channel at
+    // all, mirroring `trawl fetch`'s own --json handling.
+    const data = opts.json
+        ? await call()
+        : await oraPromise(call, { text: 'Launching scrap…', successText: 'Scrap launched' });
+    if (opts.json)
+        json(data);
     if (opts.watch) {
-        await pollRunProgress(id, beforeRun);
+        // #107 — under --json, pollRunProgress suppresses its own intermediate
+        // console.log calls and instead emits exactly ONE final NDJSON outcome
+        // line (+ sets process.exitCode honestly) once the watch reaches a
+        // terminal status, a timeout, or a persistent poll error (review F1) —
+        // `run --json --watch` never again exits 0 after dead air regardless
+        // of what the watched run actually did.
+        await pollRunProgress(id, beforeRun, { json: opts.json });
     }
 });
 // #70 — render an items array either as a table summary or --json. Shared by
@@ -893,38 +1002,50 @@ scraps
     .alias('rm')
     .description('Delete a scrap')
     .option('-f, --force', 'Skip confirmation prompt')
+    .option('--json', 'Output as JSON')
     .action(async (id, opts) => {
     validateObjectId(id);
-    if (!opts.force) {
-        const { createInterface } = await import('readline');
-        const rl = createInterface({ input: process.stdin, output: process.stdout });
-        let answer;
-        try {
-            answer = await new Promise((resolve) => {
-                rl.question(`Delete scrap ${chalk.bold(id)}? ${chalk.dim('[y/N]')} `, (a) => resolve(a.trim().toLowerCase()));
-            });
-        }
-        finally {
-            rl.close();
-        }
-        if (answer !== 'y' && answer !== 'yes') {
-            console.log(chalk.dim('Aborted.'));
-            return;
-        }
+    // #107 — never blocks on a y/N under --json or a non-TTY invocation
+    // (agent/CI subprocess); -f/--force always pre-confirms.
+    //
+    // #107 review F2 — `message` (the plain-id form) feeds the refusal
+    // UsageError, which can land verbatim in the `--json` error envelope;
+    // `chalk.bold(id)` is passed ONLY as `promptMessage`, shown solely on
+    // the interactive TTY `[y/N]` prompt. Before this split, the styled
+    // string was the ONLY message confirmDestructive had, so a non-TTY/
+    // --json refusal on `scraps delete X --json` emitted raw ANSI escape
+    // bytes inside the JSON string.
+    const { proceed, blocked } = await confirmDestructive(`Delete scrap ${id}?`, {
+        force: opts.force,
+        json: opts.json,
+        promptMessage: `Delete scrap ${chalk.bold(id)}?`,
+    });
+    if (blocked)
+        return;
+    if (!proceed) {
+        console.log(chalk.dim('Aborted.'));
+        return;
+    }
+    const call = () => api.delete(`/api/scraps/${id}`);
+    if (opts.json) {
+        await call();
+        json({ deleted: true, id });
+        return;
     }
-    await oraPromise(() => api.delete(`/api/scraps/${id}`), { text: 'Deleting…', successText: 'Scrap deleted' });
+    await oraPromise(call, { text: 'Deleting…', successText: 'Scrap deleted' });
 });
 // banner
 scraps
     .command('banner <id>')
     .description('Upload a banner image for a scrap')
     .requiredOption('-f, --file <path>', 'Path to image file (jpg, png, webp)')
+    .option('--json', 'Output as JSON')
     .action(async (id, opts) => {
     validateObjectId(id);
     const { readFileSync, existsSync } = await import('fs');
     const { basename } = await import('path');
     if (!existsSync(opts.file)) {
-        usageError(`File not found: ${opts.file}`);
+        usageError(`File not found: ${opts.file}`, { json: opts.json });
         return;
     }
     const filename = basename(opts.file);
@@ -940,14 +1061,20 @@ scraps
     // Content-Type — a lie about the actual file's format). Refuse instead.
     const mimeType = mimeMap[ext];
     if (!mimeType) {
-        usageError(`Unsupported image type "${ext ? `.${ext}` : filename}" — use png, jpg, or webp.`);
+        usageError(`Unsupported image type "${ext ? `.${ext}` : filename}" — use png, jpg, or webp.`, { json: opts.json });
         return;
     }
     const fileBuffer = readFileSync(opts.file);
     const blob = new Blob([fileBuffer], { type: mimeType });
     const formData = new FormData();
     formData.append('banner', blob, filename);
-    await oraPromise(() => api.upload(`/api/scraps/${id}/banner`, formData), {
+    const call = () => api.upload(`/api/scraps/${id}/banner`, formData);
+    if (opts.json) {
+        const data = await call();
+        json(data);
+        return;
+    }
+    await oraPromise(call, {
         text: 'Uploading banner…',
         successText: `Banner uploaded for scrap ${chalk.bold(id)}`,
     });
@@ -956,9 +1083,10 @@ scraps
 scraps
     .command('watch <id>')
     .description('Stream scrap activities in real-time')
-    .action(async (id) => {
+    .option('--json', 'Output each activity as a JSON line (NDJSON) instead of formatted text')
+    .action(async (id, opts) => {
     validateObjectId(id);
-    await watchActivities(id);
+    await watchActivities(id, opts.json);
 });
 // trigger
 scraps
@@ -966,6 +1094,7 @@ scraps
     .description('Launch a scrap as a background worker (returns immediately)')
     .option('-w, --watch', 'Poll for progress after triggering (#91 — the default async run happens in a separate cron pod; activities SSE never reaches it)')
     .option('--wait', 'Run synchronously and wait for the result (legacy behaviour)')
+    .option('--json', 'Output the raw trigger payload as JSON')
     .action(async (id, opts) => {
     validateObjectId(id);
     // #91 P1 / #93 item 1 — captured BEFORE triggering so pollRunProgress can
@@ -983,12 +1112,21 @@ scraps
     // (30-250s), same as `scraps run`; the 30s default was aborting it
     // mid-flight. The async (default) POST returns almost immediately, so it
     // keeps the 30s default.
-    await oraPromise(() => (opts.wait ? api.post(path, undefined, { timeoutMs: LONG_RUN_TIMEOUT_MS }) : api.post(path)), {
-        text: opts.wait ? 'Running worker…' : 'Triggering worker…',
-        successText: opts.wait ? 'Worker run complete' : 'Worker triggered',
-    });
+    const call = () => (opts.wait ? api.post(path, undefined, { timeoutMs: LONG_RUN_TIMEOUT_MS }) : api.post(path));
+    // #107 — under --json the stdout path stays pure: no spinner channel.
+    const data = opts.json
+        ? await call()
+        : await oraPromise(call, {
+            text: opts.wait ? 'Running worker…' : 'Triggering worker…',
+            successText: opts.wait ? 'Worker run complete' : 'Worker triggered',
+        });
+    if (opts.json)
+        json(data);
+    // #107 — see the matching comment on `run`'s --watch call above (review
+    // F1): honest final NDJSON line + exit code under --json, human mode
+    // gets the same honest exit code too.
     if (opts.watch)
-        await pollRunProgress(id, beforeRun);
+        await pollRunProgress(id, beforeRun, { json: opts.json });
 });
 // account subcommand group
 const account = scraps
@@ -1013,28 +1151,49 @@ account
     .description('Set credentials for a scrap account')
     .option('-u, --username <username>', 'Account username')
     .option('-p, --password <password>', 'Account password (insecure: prefer interactive prompt)')
+    .option('--json', 'Output as JSON')
     .action(async (id, opts) => {
     validateObjectId(id);
     let username = opts.username || '';
     let password = opts.password || '';
     if (opts.password) {
-        console.log(chalk.yellow('⚠ Passing --password on the command line is insecure and may be stored in shell history.'));
+        // #107 — this advisory is stderr-only: stdout must stay pure under
+        // --json, and every other advisory in this CLI already follows that
+        // rule (warnIfUnconfirmedTier, token.ts's expiry hints, …).
+        console.error(chalk.yellow('⚠ Passing --password on the command line is insecure and may be stored in shell history.'));
     }
+    // #107 — never blocks on a readline prompt under --json or a non-TTY
+    // invocation (agent/CI subprocess); pass -u/-p instead.
+    const interactive = isInteractive({ json: opts.json });
     if (!username) {
+        if (!interactive) {
+            usageError('Username is required — pass -u/--username (refusing to block on a prompt, non-interactive).', { json: opts.json });
+            return;
+        }
         username = await promptLine('Username: ');
         if (!username) {
-            usageError('Username is required.');
+            usageError('Username is required.', { json: opts.json });
             return;
         }
     }
     if (!password) {
+        if (!interactive) {
+            usageError('Password is required — pass -p/--password (refusing to block on a prompt, non-interactive).', { json: opts.json });
+            return;
+        }
         password = await promptPassword('Password: ');
         if (!password) {
-            usageError('Password is required.');
+            usageError('Password is required.', { json: opts.json });
             return;
         }
     }
-    const data = await oraPromise(() => api.put(`/api/scraps/${id}/account`, { username, password }), { text: 'Saving credentials…', successText: 'Credentials saved' });
+    const call = () => api.put(`/api/scraps/${id}/account`, { username, password });
+    if (opts.json) {
+        const data = await call();
+        json(data);
+        return;
+    }
+    const data = await oraPromise(call, { text: 'Saving credentials…', successText: 'Credentials saved' });
     const acc = data.account;
     console.log(chalk.dim('  Credentials: ') + (acc.hasCredentials ? chalk.green('✓ configured') : chalk.dim('not set')));
     console.log(chalk.dim('  Session:     ') + (acc.hasSession ? chalk.green('active') : chalk.dim('none')));
@@ -1044,26 +1203,27 @@ account
     .command('delete <id>')
     .description('Delete account credentials for a scrap')
     .option('-f, --force', 'Skip confirmation prompt')
+    .option('--json', 'Output as JSON')
     .action(async (id, opts) => {
     validateObjectId(id);
-    if (!opts.force) {
-        const { createInterface } = await import('readline');
-        const rl = createInterface({ input: process.stdin, output: process.stdout });
-        let answer;
-        try {
-            answer = await new Promise((resolve) => {
-                rl.question(`Delete account credentials for scrap ${chalk.bold(id)}? ${chalk.dim('[y/N]')} `, (a) => resolve(a.trim().toLowerCase()));
-            });
-        }
-        finally {
-            rl.close();
-        }
-        if (answer !== 'y' && answer !== 'yes') {
-            console.log(chalk.dim('Aborted.'));
-            return;
-        }
+    // #107 — never blocks on a y/N under --json or a non-TTY invocation.
+    // #107 review F2 — plain-id `message` for the refusal/JSON envelope,
+    // styled `promptMessage` for the interactive TTY prompt only (see the
+    // matching comment on `scraps delete` above).
+    const { proceed, blocked } = await confirmDestructive(`Delete account credentials for scrap ${id}?`, { force: opts.force, json: opts.json, promptMessage: `Delete account credentials for scrap ${chalk.bold(id)}?` });
+    if (blocked)
+        return;
+    if (!proceed) {
+        console.log(chalk.dim('Aborted.'));
+        return;
+    }
+    const call = () => api.delete(`/api/scraps/${id}/account`);
+    if (opts.json) {
+        await call();
+        json({ deleted: true, id });
+        return;
     }
-    await oraPromise(() => api.delete(`/api/scraps/${id}/account`), {
+    await oraPromise(call, {
         text: 'Deleting credentials…',
         successText: 'Account credentials deleted',
     });
@@ -1072,9 +1232,16 @@ account
 account
     .command('clear-session <id>')
     .description('Clear the saved session for a scrap account')
-    .action(async (id) => {
+    .option('--json', 'Output as JSON')
+    .action(async (id, opts) => {
     validateObjectId(id);
-    await oraPromise(() => api.delete(`/api/scraps/${id}/account/session`), {
+    const call = () => api.delete(`/api/scraps/${id}/account/session`);
+    if (opts.json) {
+        await call();
+        json({ cleared: true, id });
+        return;
+    }
+    await oraPromise(call, {
         text: 'Clearing session…',
         successText: 'Session cleared',
     });
@@ -1088,11 +1255,12 @@ accountSession
     .command('set <id>')
     .description('Upload browser session cookies for a scrap (Puppeteer cookie JSON array)')
     .requiredOption('-c, --cookies <file>', 'Path to a Puppeteer cookie JSON array file')
+    .option('--json', 'Output as JSON')
     .action(async (id, opts) => {
     validateObjectId(id);
     const { existsSync, readFileSync } = await import('fs');
     if (!existsSync(opts.cookies)) {
-        usageError(`File not found: ${opts.cookies}`);
+        usageError(`File not found: ${opts.cookies}`, { json: opts.json });
         return;
     }
     let cookies;
@@ -1101,22 +1269,31 @@ accountSession
         cookies = JSON.parse(raw);
     }
     catch (e) {
-        usageError(`Failed to parse cookies file: ${e.message}`);
+        usageError(`Failed to parse cookies file: ${e.message}`, { json: opts.json });
         return;
     }
     if (!Array.isArray(cookies)) {
-        usageError('Cookies file must contain a JSON array');
+        usageError('Cookies file must contain a JSON array', { json: opts.json });
         return;
     }
     if (cookies.length === 0) {
-        usageError('Cookies array must not be empty');
+        usageError('Cookies array must not be empty', { json: opts.json });
         return;
     }
     if (!cookies.every((c) => c && typeof c.name === 'string' && typeof c.value === 'string')) {
-        usageError('Each cookie must have a name (string) and value (string)');
+        usageError('Each cookie must have a name (string) and value (string)', { json: opts.json });
         return;
     }
-    const data = await oraPromise(() => api.put(`/api/scraps/${id}/account/session`, { cookies }), { text: 'Uploading session cookies…', successText: `Session cookies saved for scrap ${chalk.bold(id)}` });
+    const call = () => api.put(`/api/scraps/${id}/account/session`, { cookies });
+    if (opts.json) {
+        const data = await call();
+        json(data);
+        return;
+    }
+    const data = await oraPromise(call, {
+        text: 'Uploading session cookies…',
+        successText: `Session cookies saved for scrap ${chalk.bold(id)}`,
+    });
     const acc = data.account;
     console.log(chalk.dim('  Session: ') + (acc.hasSession ? chalk.green('✓ active') : chalk.dim('none')));
 });