@trawlme/cli 1.17.0 → 1.18.0

package/dist/commands/scraps.js

@@ -1,11 +1,26 @@
 import { Command } from 'commander';
 import chalk from 'chalk';
-import ora from 'ora';
+import { oraPromise } from 'ora';
 import { api } 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 } from '../lib/errors.js';
 import { formatDoctor, formatAutofix, fetchRunAndFix, pickRun, pickFix } from './doctor.js';
+/**
+ * Print a usage/validation error consistently: human text to stderr always;
+ * when the invoking command supports --json, ALSO emit a machine envelope on
+ * stdout instead of leaving stdout silent/prose. Sets exit code 2 (usage) —
+ * distinct from a business-logic refusal (which stays 1) or an unmapped
+ * ApiError/NetworkError (handled centrally in index.ts). (#71)
+ */
+function usageError(message, opts = {}) {
+    console.error(chalk.red(`✗ ${message}`));
+    if (opts.json) {
+        console.log(JSON.stringify({ error: { message, kind: 'usage' } }));
+    }
+    process.exitCode = 2;
+}
 function lastStatus(scrap) {
     const last = scrap.history?.[0];
     if (!last || last.status === null || last.status === undefined)
@@ -61,41 +76,46 @@ scraps
     .action(async (opts) => {
     // Guard: --limit and --page are mutually exclusive
     if (opts.limit !== undefined && opts.page !== undefined) {
-        console.log(chalk.red('✗ --limit and --page are mutually exclusive. Use one or the other.'));
-        process.exitCode = 1;
+        usageError('--limit and --page are mutually exclusive. Use one or the other.', { json: opts.json });
         return;
     }
-    const spinner = ora('Fetching scraps…').start();
     let data;
     try {
-        if (opts.page !== undefined) {
-            // Single-page mode: explicit page requested, no loop
-            const pageNum = opts.page;
-            data = await api.get(`/api/scraps?perPage=50&page=${pageNum}`);
-        }
-        else {
+        data = await oraPromise(async () => {
+            if (opts.page !== undefined) {
+                // Single-page mode: explicit page requested, no loop
+                const pageNum = opts.page;
+                return api.get(`/api/scraps?perPage=50&page=${pageNum}`);
+            }
             // Fetch-all mode: paginate until a page returns < 200 items
             const perPage = 200;
-            data = [];
+            let result = [];
             let page = 1;
             while (true) {
                 const batch = await api.get(`/api/scraps?perPage=${perPage}&page=${page}`);
-                data = data.concat(batch);
+                result = result.concat(batch);
                 if (batch.length < perPage)
                     break;
                 page++;
             }
-        }
+            return result;
+        }, 'Fetching scraps…');
     }
     catch (err) {
-        spinner.stop();
-        console.log(chalk.red(`✗ Failed to fetch scraps: ${err.message}`));
-        process.exitCode = 1;
+        // Spinner already failed by oraPromise — report with the scrap-specific
+        // prefix kept, but route through the shared classifier so exit code +
+        // --json envelope stay consistent with every other command. (#71)
+        const { exitCode, envelope } = classifyError(err);
+        const message = `Failed to fetch scraps: ${envelope.message}`;
+        if (opts.json) {
+            console.log(JSON.stringify({ error: { ...envelope, message } }));
+        }
+        else {
+            console.error(chalk.red(`✗ ${message}`));
+        }
+        process.exitCode = exitCode;
         return;
     }
-    finally {
-        spinner.stop();
-    }
     if (opts.status)
         data = data.filter((s) => lastStatus(s) === opts.status);
     const totalMatched = data.length;
@@ -146,19 +166,16 @@ scraps
     .option('--tier <tier>', `Force proxy tier (${VALID_TIERS.join('|')})`)
     .action(async (opts) => {
     if (opts.tier !== undefined && !VALID_TIERS.includes(opts.tier)) {
-        console.log(chalk.red(`✗ Invalid --tier "${opts.tier}" (allowed: ${VALID_TIERS.join(', ')})`));
-        process.exitCode = 1;
+        usageError(`Invalid --tier "${opts.tier}" (allowed: ${VALID_TIERS.join(', ')})`);
         return;
     }
-    const spinner = ora('Creating scrap…').start();
-    const data = await api.post('/api/scraps', {
+    const data = await oraPromise(() => api.post('/api/scraps', {
         title: opts.title,
         ...(opts.url && { url: opts.url }),
         request: opts.request || '',
         ...(opts.description !== undefined && { description: opts.description }),
         ...(opts.tier !== undefined && { proxyTier: opts.tier }),
-    });
-    spinner.succeed(`Scrap created: ${chalk.bold(data._id)}`);
+    }), { text: 'Creating scrap…', successText: (d) => `Scrap created: ${chalk.bold(d._id)}` });
     console.log(chalk.dim(`  Title: ${data.title}`));
 });
 // update
@@ -182,13 +199,11 @@ scraps
     .action(async (id, opts) => {
     validateObjectId(id);
     if (opts.tier !== undefined && !VALID_TIERS.includes(opts.tier)) {
-        console.log(chalk.red(`✗ Invalid --tier "${opts.tier}" (allowed: ${VALID_TIERS.join(', ')})`));
-        process.exitCode = 1;
+        usageError(`Invalid --tier "${opts.tier}" (allowed: ${VALID_TIERS.join(', ')})`);
         return;
     }
     if (opts.forceTier !== undefined && !VALID_TIERS.includes(opts.forceTier)) {
-        console.log(chalk.red(`✗ Invalid --force-tier "${opts.forceTier}" (allowed: ${VALID_TIERS.join(', ')})`));
-        process.exitCode = 1;
+        usageError(`Invalid --force-tier "${opts.forceTier}" (allowed: ${VALID_TIERS.join(', ')})`);
         return;
     }
     const body = {};
@@ -226,13 +241,11 @@ scraps
             parsed = JSON.parse(raw);
         }
         catch (e) {
-            console.log(chalk.red(`✗ Invalid JSON for --params: ${e.message}`));
-            process.exitCode = 1;
+            usageError(`Invalid JSON for --params: ${e.message}`);
             return;
         }
         if (!Array.isArray(parsed)) {
-            console.log(chalk.red('✗ --params must be a JSON array of objects'));
-            process.exitCode = 1;
+            usageError('--params must be a JSON array of objects');
             return;
         }
         body.params = parsed;
@@ -249,9 +262,10 @@ scraps
         console.log(chalk.yellow('Nothing to update. Provide at least one option.'));
         return;
     }
-    const spinner = ora('Updating scrap…').start();
-    const data = await api.put(`/api/scraps/${id}`, body);
-    spinner.succeed(`Scrap updated: ${chalk.bold(data._id)}`);
+    const data = await oraPromise(() => api.put(`/api/scraps/${id}`, body), {
+        text: 'Updating scrap…',
+        successText: (d) => `Scrap updated: ${chalk.bold(d._id)}`,
+    });
     // #1559 — surface the effective tier + clamp/refuse reason (fixes the
     // silent-clamp: the server may persist a lower tier than requested).
     const ov = data._tierOverride;
@@ -268,7 +282,7 @@ scraps
     }
     if (ov) {
         if (ov.refused) {
-            console.log(chalk.red(`  ✗ tier ceiling override refused: ${ov.reason ?? 'unknown'}`)
+            console.error(chalk.red(`  ✗ tier ceiling override refused: ${ov.reason ?? 'unknown'}`)
                 + chalk.dim(` (requested ${ov.requestedMaxTier ?? '—'}; kept the registry cap)`));
             process.exitCode = 1;
         }
@@ -296,9 +310,10 @@ scraps
     .option('-w, --watch', 'Stream activities after launching')
     .action(async (id, opts) => {
     validateObjectId(id);
-    const spinner = ora('Launching scrap…').start();
-    await api.get(`/api/scraps/load/${id}`);
-    spinner.succeed('Scrap launched');
+    await oraPromise(() => api.get(`/api/scraps/load/${id}`), {
+        text: 'Launching scrap…',
+        successText: 'Scrap launched',
+    });
     if (opts.watch) {
         await watchActivities(id);
     }
@@ -331,15 +346,22 @@ scraps
     if (opts.errors) {
         const result = await fetchRunAndFix(id);
         if (!result) {
+            if (opts.json) {
+                json(null);
+                return;
+            }
             console.log(chalk.dim('No runs yet.'));
             return;
         }
+        // --json is honored for BOTH outcomes (success or failure) — an agent
+        // parsing `data --errors --json` must always get the flat run object,
+        // never prose gated behind a status check. (#71 finding 13)
+        if (opts.json)
+            return json(pickRun(result.run));
         if (result.run.status === true) {
             console.log(chalk.green('✓ Last run succeeded. No errors to show.'));
             return;
         }
-        if (opts.json)
-            return json(pickRun(result.run));
         console.log(formatDoctor(result.scrap.title, result.run, result.fix, id));
         return;
     }
@@ -350,11 +372,18 @@ scraps
     // burning execute quota and 429ing if a run is already in flight. A user
     // or agent "just reading data" must never trigger that by accident.
     if (opts.fresh) {
-        const spinner = ora('Launching a fresh scrap run (consumes execute quota)…').start();
-        const loaded = await api.get(`/api/scraps/load/${id}`);
-        spinner.succeed('Fresh run complete');
+        const loaded = await oraPromise(() => api.get(`/api/scraps/load/${id}`), {
+            text: 'Launching a fresh scrap run (consumes execute quota)…',
+            successText: 'Fresh run complete',
+        });
         const items = loaded?.result?.data;
         if (!Array.isArray(items)) {
+            // --json always returns an array from `data` — [] is the honest
+            // "no items" signal instead of prose breaking JSON parsing. (#71)
+            if (opts.json) {
+                json([]);
+                return;
+            }
             console.log(chalk.dim('No data yet. Run the scrap first.'));
             return;
         }
@@ -371,6 +400,10 @@ scraps
     const scrap = await api.get(`/api/scraps/${id}`);
     const hid = scrap.history?.[0]?._id;
     if (!hid) {
+        if (opts.json) {
+            json([]);
+            return;
+        }
         console.log(chalk.dim('No data yet. Run the scrap first, or pass --fresh to launch one now.'));
         return;
     }
@@ -385,6 +418,10 @@ scraps
         }
     }
     if (!Array.isArray(items)) {
+        if (opts.json) {
+            json([]);
+            return;
+        }
         console.log(chalk.dim('No persisted data for the last run (it may have failed, or aged out of retention). '
             + 'Pass --fresh to launch a new run (consumes execute quota).'));
         return;
@@ -401,8 +438,7 @@ scraps
     validateObjectId(id);
     const limit = Number(opts.limit);
     if (!Number.isInteger(limit) || limit < 1) {
-        console.log(chalk.red(`✗ Invalid --limit "${opts.limit}" (expected a positive integer)`));
-        process.exitCode = 1;
+        usageError(`Invalid --limit "${opts.limit}" (expected a positive integer)`, { json: opts.json });
         return;
     }
     const scrap = await api.get(`/api/scraps/${id}`);
@@ -472,9 +508,7 @@ scraps
             return;
         }
     }
-    const spinner = ora('Deleting…').start();
-    await api.delete(`/api/scraps/${id}`);
-    spinner.succeed('Scrap deleted');
+    await oraPromise(() => api.delete(`/api/scraps/${id}`), { text: 'Deleting…', successText: 'Scrap deleted' });
 });
 // banner
 scraps
@@ -486,8 +520,7 @@ scraps
     const { readFileSync, existsSync } = await import('fs');
     const { basename } = await import('path');
     if (!existsSync(opts.file)) {
-        console.log(chalk.red(`✗ File not found: ${opts.file}`));
-        process.exitCode = 1;
+        usageError(`File not found: ${opts.file}`);
         return;
     }
     const fileBuffer = readFileSync(opts.file);
@@ -503,9 +536,10 @@ scraps
     const blob = new Blob([fileBuffer], { type: mimeType });
     const formData = new FormData();
     formData.append('banner', blob, filename);
-    const spinner = ora('Uploading banner…').start();
-    await api.upload(`/api/scraps/${id}/banner`, formData);
-    spinner.succeed(`Banner uploaded for scrap ${chalk.bold(id)}`);
+    await oraPromise(() => api.upload(`/api/scraps/${id}/banner`, formData), {
+        text: 'Uploading banner…',
+        successText: `Banner uploaded for scrap ${chalk.bold(id)}`,
+    });
 });
 // watch (stream activities)
 scraps
@@ -523,13 +557,14 @@ scraps
     .option('--wait', 'Run synchronously and wait for the result (legacy behaviour)')
     .action(async (id, opts) => {
     validateObjectId(id);
-    const spinner = ora(opts.wait ? 'Running worker…' : 'Triggering worker…').start();
     // #50 — default async: the backend (#1313) kicks off the run and returns a
     // 'queued' envelope immediately instead of holding the connection for the
     // whole run. --wait restores the old synchronous round-trip.
     const path = opts.wait ? `/api/scraps/worker/${id}` : `/api/scraps/worker/${id}?wait=false`;
-    await api.post(path);
-    spinner.succeed(opts.wait ? 'Worker run complete' : 'Worker triggered');
+    await oraPromise(() => api.post(path), {
+        text: opts.wait ? 'Running worker…' : 'Triggering worker…',
+        successText: opts.wait ? 'Worker run complete' : 'Worker triggered',
+    });
     if (opts.watch)
         await watchActivities(id);
 });
@@ -566,22 +601,18 @@ account
     if (!username) {
         username = await promptLine('Username: ');
         if (!username) {
-            console.log(chalk.red('✗ Username is required.'));
-            process.exitCode = 1;
+            usageError('Username is required.');
             return;
         }
     }
     if (!password) {
         password = await promptPassword('Password: ');
         if (!password) {
-            console.log(chalk.red('✗ Password is required.'));
-            process.exitCode = 1;
+            usageError('Password is required.');
             return;
         }
     }
-    const spinner = ora('Saving credentials…').start();
-    const data = await api.put(`/api/scraps/${id}/account`, { username, password });
-    spinner.succeed('Credentials saved');
+    const data = await oraPromise(() => api.put(`/api/scraps/${id}/account`, { username, password }), { 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')));
@@ -610,9 +641,10 @@ account
             return;
         }
     }
-    const spinner = ora('Deleting credentials…').start();
-    await api.delete(`/api/scraps/${id}/account`);
-    spinner.succeed('Account credentials deleted');
+    await oraPromise(() => api.delete(`/api/scraps/${id}/account`), {
+        text: 'Deleting credentials…',
+        successText: 'Account credentials deleted',
+    });
 });
 // account clear-session
 account
@@ -620,9 +652,10 @@ account
     .description('Clear the saved session for a scrap account')
     .action(async (id) => {
     validateObjectId(id);
-    const spinner = ora('Clearing session…').start();
-    await api.delete(`/api/scraps/${id}/account/session`);
-    spinner.succeed('Session cleared');
+    await oraPromise(() => api.delete(`/api/scraps/${id}/account/session`), {
+        text: 'Clearing session…',
+        successText: 'Session cleared',
+    });
 });
 // account session subcommand group
 const accountSession = account
@@ -637,8 +670,7 @@ accountSession
     validateObjectId(id);
     const { existsSync, readFileSync } = await import('fs');
     if (!existsSync(opts.cookies)) {
-        console.log(chalk.red(`✗ File not found: ${opts.cookies}`));
-        process.exitCode = 1;
+        usageError(`File not found: ${opts.cookies}`);
         return;
     }
     let cookies;
@@ -647,28 +679,22 @@ accountSession
         cookies = JSON.parse(raw);
     }
     catch (e) {
-        console.log(chalk.red(`✗ Failed to parse cookies file: ${e.message}`));
-        process.exitCode = 1;
+        usageError(`Failed to parse cookies file: ${e.message}`);
         return;
     }
     if (!Array.isArray(cookies)) {
-        console.log(chalk.red('✗ Cookies file must contain a JSON array'));
-        process.exitCode = 1;
+        usageError('Cookies file must contain a JSON array');
         return;
     }
     if (cookies.length === 0) {
-        console.log(chalk.red('✗ Cookies array must not be empty'));
-        process.exitCode = 1;
+        usageError('Cookies array must not be empty');
         return;
     }
     if (!cookies.every((c) => c && typeof c.name === 'string' && typeof c.value === 'string')) {
-        console.log(chalk.red('✗ Each cookie must have a name (string) and value (string)'));
-        process.exitCode = 1;
+        usageError('Each cookie must have a name (string) and value (string)');
         return;
     }
-    const spinner = ora('Uploading session cookies…').start();
-    const data = await api.put(`/api/scraps/${id}/account/session`, { cookies });
-    spinner.succeed(`Session cookies saved for scrap ${chalk.bold(id)}`);
+    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 acc = data.account;
     console.log(chalk.dim('  Session: ') + (acc.hasSession ? chalk.green('✓ active') : chalk.dim('none')));
 });
@@ -679,9 +705,7 @@ account
     .option('--json', 'Output as JSON')
     .action(async (id, opts) => {
     validateObjectId(id);
-    const spinner = ora('Fetching scrap…').start();
-    const data = await api.get(`/api/scraps/${id}`);
-    spinner.stop();
+    const data = await oraPromise(() => api.get(`/api/scraps/${id}`), 'Fetching scrap…');
     const acc = data.account;
     if (opts.json) {
         const { json: jsonFn } = await import('../lib/format.js');
@@ -723,6 +747,10 @@ scraps
     validateObjectId(id);
     const result = await fetchRunAndFix(id);
     if (!result) {
+        if (opts.json) {
+            json({ status: 'no_runs' });
+            return;
+        }
         console.log(chalk.dim('No runs yet.'));
         return;
     }
@@ -742,10 +770,18 @@ scraps
     validateObjectId(id);
     const result = await fetchRunAndFix(id);
     if (!result) {
+        if (opts.json) {
+            json(null);
+            return;
+        }
         console.log(chalk.dim('No runs yet.'));
         return;
     }
     if (!result.fix) {
+        if (opts.json) {
+            json(null);
+            return;
+        }
         console.log(chalk.dim('No auto-fix attempt on the last run.'));
         return;
     }

package/dist/index.js

@@ -11,6 +11,7 @@ import { telemetry } from './commands/telemetry.js';
 import { token } from './commands/token.js';
 import { autoUpdateInstalledSkills } from './lib/skills.js';
 import { initPostHog, captureCommand, shutdown, registerAllowedCommands } from './lib/posthog.js';
+import { classifyError } from './lib/errors.js';
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8'));
 /**
@@ -91,19 +92,31 @@ export async function runCli(argv = process.argv) {
         await program.parseAsync(argv);
     }
     catch (err) {
+        // Map the error to a distinct exit code + machine envelope instead of a
+        // uniform 1 — agents driving this CLI unattended need to tell
+        // auth-expired (3) from not-found (4) from network-down (5) from a bad
+        // flag (2) apart from an arbitrary bug (1). (#71)
+        const { exitCode, envelope } = classifyError(err);
         // Capture error telemetry from the resolved command only — never argv.
         void captureCommand(resolveCommandName(currentCommand), {
-            exit_code: 1,
+            exit_code: exitCode,
             error: err.name,
         });
         const { debug } = program.opts();
-        if (debug || process.env['DEBUG']) {
+        const isDebug = Boolean(debug || process.env['DEBUG']);
+        // A --json subcommand must keep stdout pure JSON even on failure — read
+        // the resolved command's own --json flag (never argv) so the error
+        // envelope lands on the same channel the success path would have used.
+        const wantsJson = Boolean(currentCommand?.opts()?.json);
+        if (isDebug)
             console.error(err);
+        if (wantsJson) {
+            console.log(JSON.stringify({ error: envelope }));
         }
-        else {
-            console.error(chalk.red('✗ ' + err.message));
+        else if (!isDebug) {
+            console.error(chalk.red('✗ ' + envelope.message));
         }
-        process.exitCode = 1;
+        process.exitCode = exitCode;
     }
     finally {
         // Flush + close telemetry before the process exits. A `process.on('exit')`

package/dist/lib/api.d.ts

@@ -1,3 +1,16 @@
+export declare class ApiError extends Error {
+    status: number;
+    constructor(status: number, message: string);
+}
+/**
+ * A fetch-level failure — the request never got a response at all (DNS,
+ * connection refused, timeout, TLS, …). Distinguished from ApiError (which
+ * always carries a real HTTP status) so the top-level handler can map it to
+ * its own exit code instead of the generic uniform 1. (#71 findings 4/58)
+ */
+export declare class NetworkError extends Error {
+    constructor(message: string);
+}
 export declare const api: {
     get: <T>(path: string) => Promise<T>;
     getText: (path: string) => Promise<string>;

package/dist/lib/api.js

@@ -5,7 +5,7 @@ import { getApiUrl, getToken } from './config.js';
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(resolve(__dirname, '../../package.json'), 'utf8'));
 const USER_AGENT = `@trawlme/cli/${pkg.version}`;
-class ApiError extends Error {
+export class ApiError extends Error {
     status;
     constructor(status, message) {
         super(message);
@@ -13,7 +13,57 @@ class ApiError extends Error {
         this.name = 'ApiError';
     }
 }
-function extractErrorMessage(raw) {
+/**
+ * A fetch-level failure — the request never got a response at all (DNS,
+ * connection refused, timeout, TLS, …). Distinguished from ApiError (which
+ * always carries a real HTTP status) so the top-level handler can map it to
+ * its own exit code instead of the generic uniform 1. (#71 findings 4/58)
+ */
+export class NetworkError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'NetworkError';
+    }
+}
+const DEFAULT_TIMEOUT_MS = 30_000;
+/** Effective fetch timeout — TRAWL_TIMEOUT env override (ms), default 30s. (#71) */
+function getTimeoutMs() {
+    const raw = process.env['TRAWL_TIMEOUT']?.trim();
+    if (!raw)
+        return DEFAULT_TIMEOUT_MS;
+    const n = Number(raw);
+    return Number.isFinite(n) && n > 0 ? n : DEFAULT_TIMEOUT_MS;
+}
+/**
+ * Wrap a `fetch()` call so connection-level failures (ECONNREFUSED, DNS,
+ * timeout, …) surface as a NetworkError carrying the effective URL + the
+ * unwrapped `err.cause` detail, instead of a bare "fetch failed" with no
+ * actionable information. (#71 findings 4/58)
+ */
+async function safeFetch(url, options) {
+    try {
+        return await fetch(url, options);
+    }
+    catch (err) {
+        const e = err;
+        if (e?.name === 'TimeoutError' || e?.name === 'AbortError') {
+            throw new NetworkError(`Request to ${url} timed out after ${getTimeoutMs()}ms (override with TRAWL_TIMEOUT env var, ms)`);
+        }
+        const cause = e?.cause;
+        const causeDetail = cause?.code ? ` (${cause.code})` : cause?.message ? ` (${cause.message})` : '';
+        throw new NetworkError(`Network error reaching ${url}${causeDetail}: ${e?.message ?? String(err)}`);
+    }
+}
+/**
+ * Extract the honest client-facing error string from a raw response body.
+ * The server envelope (lib/helpers/responses.js) shape is
+ * `{ type, message, code, status, errorCode, description, error? }` — where
+ * `message` is sometimes a bare HTTP reason phrase (e.g. "Payment Required")
+ * duplicating `res.statusText`, producing a tautology like
+ * "402 Payment Required: Payment Required". When that happens, prefer the
+ * richer `description` field instead. (#71 finding 76 — error-copy part only)
+ */
+function extractErrorMessage(raw, statusText) {
     if (!raw)
         return '';
     try {
@@ -34,8 +84,15 @@ function extractErrorMessage(raw) {
                     return nested;
                 }
             }
-            if (typeof env.message === 'string')
-                return env.message;
+            const message = typeof env.message === 'string' ? env.message : undefined;
+            const description = typeof env.description === 'string' && env.description ? env.description : undefined;
+            if (message && description && statusText && message.toLowerCase() === statusText.toLowerCase()) {
+                return description;
+            }
+            if (message)
+                return message;
+            if (description)
+                return description;
         }
     }
     catch {
@@ -43,17 +100,67 @@ function extractErrorMessage(raw) {
     }
     return raw;
 }
+/**
+ * Best-effort extraction of an upgrade URL from a 402 response body. In
+ * production the envelope rarely carries it directly (billing.quota.service
+ * nests `upgradeUrl` inside AppError.details, which `responses.error` only
+ * serializes to the dev-only `error` string) — so this checks the top-level
+ * field, `details.upgradeUrl`, and the dev-only nested `error` JSON string,
+ * and returns null (never fabricates) when none are present. (#71 finding 76)
+ */
+function extractUpgradeUrl(raw) {
+    try {
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.upgradeUrl === 'string')
+            return parsed.upgradeUrl;
+        const details = parsed.details;
+        if (details && typeof details === 'object' && typeof details.upgradeUrl === 'string') {
+            return details.upgradeUrl;
+        }
+        if (typeof parsed.error === 'string') {
+            try {
+                const inner = JSON.parse(parsed.error);
+                if (typeof inner.upgradeUrl === 'string')
+                    return inner.upgradeUrl;
+                const innerDetails = inner.details;
+                if (innerDetails &&
+                    typeof innerDetails === 'object' &&
+                    typeof innerDetails.upgradeUrl === 'string') {
+                    return innerDetails.upgradeUrl;
+                }
+            }
+            catch {
+                // dev-only nested string wasn't JSON — nothing to extract
+            }
+        }
+    }
+    catch {
+        // not JSON — nothing to extract
+    }
+    return null;
+}
 async function throwIfError(res, isPublic = false) {
     if (res.status === 401 && !isPublic) {
         throw new ApiError(401, 'Session expired or invalid. Run: trawl login');
     }
     if (!res.ok) {
         const raw = await res.text();
-        const message = extractErrorMessage(raw);
+        const message = extractErrorMessage(raw, res.statusText);
         if (res.status === 401 && isPublic) {
             throw new ApiError(401, `Invalid credentials${message ? `: ${message}` : ''}`);
         }
-        throw new ApiError(res.status, `${res.status} ${res.statusText}: ${message}`);
+        let full = message;
+        if (res.status === 402) {
+            const upgradeUrl = extractUpgradeUrl(raw);
+            if (upgradeUrl)
+                full += ` — upgrade: ${upgradeUrl}`;
+        }
+        if (res.status === 429) {
+            const retryAfter = res.headers?.get?.('retry-after');
+            if (retryAfter)
+                full += ` (retry after ${retryAfter}s)`;
+        }
+        throw new ApiError(res.status, `${res.status} ${res.statusText}: ${full}`);
     }
 }
 async function request(path, options = {}) {
@@ -61,8 +168,9 @@ async function request(path, options = {}) {
     if (!token)
         throw new Error('Not logged in. Run: trawl login');
     const url = `${getApiUrl()}${path}`;
-    const res = await fetch(url, {
+    const res = await safeFetch(url, {
         ...options,
+        signal: AbortSignal.timeout(getTimeoutMs()),
         headers: {
             'Content-Type': 'application/json',
             'User-Agent': USER_AGENT,
@@ -92,9 +200,10 @@ async function upload(path, formData) {
         throw new Error('Not logged in. Run: trawl login');
     const url = `${getApiUrl()}${path}`;
     // Do NOT set Content-Type — fetch sets it automatically with the correct multipart boundary
-    const res = await fetch(url, {
+    const res = await safeFetch(url, {
         method: 'POST',
         body: formData,
+        signal: AbortSignal.timeout(getTimeoutMs()),
         headers: {
             'User-Agent': USER_AGENT,
             Cookie: `TOKEN=${token}`,
@@ -118,10 +227,11 @@ async function upload(path, formData) {
 }
 async function publicPost(path, body, baseUrlOverride) {
     const url = `${baseUrlOverride ?? getApiUrl()}${path}`;
-    const res = await fetch(url, {
+    const res = await safeFetch(url, {
         method: 'POST',
         headers: { 'Content-Type': 'application/json', 'User-Agent': USER_AGENT },
         body: body ? JSON.stringify(body) : undefined,
+        signal: AbortSignal.timeout(getTimeoutMs()),
     });
     await throwIfError(res, true);
     const text = await res.text();
@@ -138,11 +248,12 @@ async function getText(path) {
     if (!token)
         throw new Error('Not logged in. Run: trawl login');
     const url = `${getApiUrl()}${path}`;
-    const res = await fetch(url, {
+    const res = await safeFetch(url, {
         headers: {
             'User-Agent': USER_AGENT,
             Cookie: `TOKEN=${token}`,
         },
+        signal: AbortSignal.timeout(getTimeoutMs()),
     });
     await throwIfError(res);
     return res.text();
@@ -166,7 +277,10 @@ export const api = {
         if (!token)
             throw new Error('Not logged in. Run: trawl login');
         const url = `${getApiUrl()}${path}`;
-        const res = await fetch(url, {
+        // No AbortSignal.timeout here — a long-running `watch`/`--watch` stream is
+        // expected to sit open indefinitely; only connection-level failures
+        // (never a timeout) should surface via safeFetch's cause-unwrapping. (#71)
+        const res = await safeFetch(url, {
             headers: {
                 Accept: 'text/event-stream',
                 'User-Agent': USER_AGENT,

package/dist/lib/errors.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Thrown for CLI usage / input-validation failures (bad flag value, malformed
+ * JSON, invalid ObjectId, missing required prompt input, …). Distinguished
+ * from ApiError/NetworkError so the top-level handler can map it to its own
+ * exit code (2) instead of the generic uniform 1 every other bug collapses
+ * into. (#71)
+ */
+export declare class UsageError extends Error {
+    constructor(message: string);
+}
+export interface ErrorEnvelope {
+    message: string;
+    status?: number;
+    kind: string;
+}
+export interface ClassifiedError {
+    exitCode: number;
+    envelope: ErrorEnvelope;
+}
+/**
+ * Central status → exit-code map (#71 findings 13/14/60). Agents driving this
+ * CLI unattended need to tell "you're not logged in" (3) from "that id
+ * doesn't exist" (4) from "the network/API is unreachable" (5) from "you
+ * passed a bad flag" (2) — a uniform exit 1 collapses all of these into one
+ * undifferentiable signal.
+ */
+export declare function classifyError(err: unknown): ClassifiedError;
+/**
+ * Print a classified error to the correct stream and return its exit code.
+ * stdout is reserved for payload — under --json the error itself IS the
+ * payload (`{"error":{message,status,kind}}`); otherwise the human-readable
+ * line goes to stderr, never stdout. (#71 findings 13/14/60)
+ *
+ * `quiet` skips the human-readable stderr line (used when the caller already
+ * printed a fuller diagnostic, e.g. a raw stack trace under --debug) while
+ * still emitting the --json payload when requested.
+ */
+export declare function reportError(err: unknown, opts?: {
+    json?: boolean;
+    quiet?: boolean;
+}): number;

package/dist/lib/errors.js

@@ -0,0 +1,59 @@
+import chalk from 'chalk';
+import { ApiError, NetworkError } from './api.js';
+/**
+ * Thrown for CLI usage / input-validation failures (bad flag value, malformed
+ * JSON, invalid ObjectId, missing required prompt input, …). Distinguished
+ * from ApiError/NetworkError so the top-level handler can map it to its own
+ * exit code (2) instead of the generic uniform 1 every other bug collapses
+ * into. (#71)
+ */
+export class UsageError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'UsageError';
+    }
+}
+/**
+ * Central status → exit-code map (#71 findings 13/14/60). Agents driving this
+ * CLI unattended need to tell "you're not logged in" (3) from "that id
+ * doesn't exist" (4) from "the network/API is unreachable" (5) from "you
+ * passed a bad flag" (2) — a uniform exit 1 collapses all of these into one
+ * undifferentiable signal.
+ */
+export function classifyError(err) {
+    const message = err instanceof Error ? err.message : String(err);
+    if (err instanceof ApiError) {
+        if (err.status === 401)
+            return { exitCode: 3, envelope: { message, status: 401, kind: 'auth' } };
+        if (err.status === 404)
+            return { exitCode: 4, envelope: { message, status: 404, kind: 'not_found' } };
+        return { exitCode: 1, envelope: { message, status: err.status, kind: 'api' } };
+    }
+    if (err instanceof NetworkError) {
+        return { exitCode: 5, envelope: { message, kind: 'network' } };
+    }
+    if (err instanceof UsageError) {
+        return { exitCode: 2, envelope: { message, kind: 'usage' } };
+    }
+    return { exitCode: 1, envelope: { message, kind: 'unknown' } };
+}
+/**
+ * Print a classified error to the correct stream and return its exit code.
+ * stdout is reserved for payload — under --json the error itself IS the
+ * payload (`{"error":{message,status,kind}}`); otherwise the human-readable
+ * line goes to stderr, never stdout. (#71 findings 13/14/60)
+ *
+ * `quiet` skips the human-readable stderr line (used when the caller already
+ * printed a fuller diagnostic, e.g. a raw stack trace under --debug) while
+ * still emitting the --json payload when requested.
+ */
+export function reportError(err, opts = {}) {
+    const { exitCode, envelope } = classifyError(err);
+    if (opts.json) {
+        console.log(JSON.stringify({ error: envelope }));
+    }
+    else if (!opts.quiet) {
+        console.error(chalk.red('✗ ' + envelope.message));
+    }
+    return exitCode;
+}

package/dist/lib/validate.js

@@ -1,12 +1,13 @@
 import { decodeExp } from './jwt.js';
+import { UsageError } from './errors.js';
 export function validateObjectId(id) {
     if (!/^[0-9a-fA-F]{24}$/.test(id)) {
-        throw new Error(`Invalid scrap ID: "${id}" — expected a 24-char hex ObjectId`);
+        throw new UsageError(`Invalid scrap ID: "${id}" — expected a 24-char hex ObjectId`);
     }
 }
 export function requireString(value, name) {
     if (typeof value !== 'string' || value.trim() === '') {
-        throw new Error(`${name} is required and must be a non-empty string`);
+        throw new UsageError(`${name} is required and must be a non-empty string`);
     }
     return value.trim();
 }
@@ -15,20 +16,20 @@ export function requireUrl(value, name) {
     try {
         const url = new URL(str);
         if (url.protocol !== 'http:' && url.protocol !== 'https:') {
-            throw new Error(`${name} must use http or https protocol`);
+            throw new UsageError(`${name} must use http or https protocol`);
         }
     }
     catch (err) {
         if (err instanceof Error && err.message.startsWith(name))
             throw err;
-        throw new Error(`${name} must be a valid URL`);
+        throw new UsageError(`${name} must be a valid URL`);
     }
     return str;
 }
 export function requireJwt(value, name) {
     const str = requireString(value, name);
     if (str.split('.').length !== 3) {
-        throw new Error(`${name} must be a valid JWT token`);
+        throw new UsageError(`${name} must be a valid JWT token`);
     }
     return str;
 }
@@ -45,7 +46,7 @@ export function requireFreshJwt(value, name) {
     const exp = decodeExp(jwt);
     const nowSeconds = Math.floor(Date.now() / 1000);
     if (exp !== null && exp < nowSeconds) {
-        throw new Error(`${name} is an expired JWT (exp has already passed) — obtain a fresh token and retry`);
+        throw new UsageError(`${name} is an expired JWT (exp has already passed) — obtain a fresh token and retry`);
     }
     return jwt;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trawlme/cli",
-  "version": "1.17.0",
+  "version": "1.18.0",
   "description": "Trawl CLI — manage scraps from the terminal",
   "type": "module",
   "bin": {