@trawlme/cli 1.16.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
@@ -178,11 +195,15 @@ scraps
     .option('-p, --params <json>', 'Runtime params as JSON array of objects (e.g. \'[{"TRAWL.paramName":"value"}]\')')
     .option('--params-file <path>', 'Runtime params from a JSON file')
     .option('--tier <tier>', `Force proxy tier (${VALID_TIERS.join('|')})`)
+    .option('--force-tier <tier>', `Raise the proxy-tier ceiling PAST the auto-cap (${VALID_TIERS.join('|')}) — history-gated: may be refused or cost more`)
     .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)) {
+        usageError(`Invalid --force-tier "${opts.forceTier}" (allowed: ${VALID_TIERS.join(', ')})`);
         return;
     }
     const body = {};
@@ -220,28 +241,66 @@ 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;
     }
     if (opts.tier !== undefined)
         body.proxyTier = opts.tier;
+    if (opts.forceTier !== undefined) {
+        // Raise the ceiling; also start the run at that tier unless --tier says otherwise.
+        body.proxyMaxTier = opts.forceTier;
+        if (opts.tier === undefined)
+            body.proxyTier = opts.forceTier;
+    }
     if (Object.keys(body).length === 0) {
         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;
+    const shown = data;
     for (const key of Object.keys(body)) {
-        console.log(chalk.dim(`  ${key}: `) + String(data[key] ?? '—'));
+        // Only suppress the raw proxyTier/proxyMaxTier echo when _tierOverride is
+        // present to report the truth. Against an older server (no _tierOverride)
+        // fall back to echoing the requested value from the body, so the tier is
+        // never silently dropped (worse than a misleading echo).
+        if ((key === 'proxyTier' || key === 'proxyMaxTier') && ov)
+            continue;
+        const src = key in shown ? shown[key] : body[key];
+        console.log(chalk.dim(`  ${key}: `) + String(src ?? '—'));
+    }
+    if (ov) {
+        if (ov.refused) {
+            console.error(chalk.red(`  ✗ tier ceiling override refused: ${ov.reason ?? 'unknown'}`)
+                + chalk.dim(` (requested ${ov.requestedMaxTier ?? '—'}; kept the registry cap)`));
+            process.exitCode = 1;
+        }
+        else if (ov.effectiveMaxTier) {
+            console.log(chalk.green(`  ✓ tier ceiling: ${ov.effectiveMaxTier}`)
+                + chalk.dim(` (${ov.reason ?? ''}${ov.provider ? `, ${ov.provider}` : ''})`));
+            if (ov.warning)
+                console.log(chalk.yellow(`    ⚠ ${ov.warning}`));
+        }
+        if (ov.proxyTier) {
+            if (ov.proxyTier.clamped) {
+                console.log(chalk.yellow(`  ⚠ proxyTier requested ${ov.proxyTier.requested} → applied ${ov.proxyTier.effective}`)
+                    + chalk.dim(` (${ov.proxyTier.reason ?? 'capped'})`));
+            }
+            else {
+                console.log(chalk.dim(`  proxyTier: `) + ov.proxyTier.effective);
+            }
+        }
     }
 });
 // run
@@ -251,51 +310,123 @@ 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);
     }
 });
+// #70 — render an items array either as a table summary or --json. Shared by
+// both the default (persisted read) and --fresh (live execute) paths of `data`.
+function renderScrapItems(items, asJson) {
+    if (asJson) {
+        json(items);
+        return;
+    }
+    console.log(chalk.bold('Last run data:'));
+    console.log(chalk.dim(`  Items: ${items.length}`));
+    if (items.length > 0 && typeof items[0] === 'object' && items[0] !== null) {
+        console.log(chalk.dim(`  First item keys: ${Object.keys(items[0]).join(', ')}`));
+    }
+    console.log(chalk.dim('  Use --json for full output.'));
+}
 // data
 scraps
     .command('data <id>')
-    .description('Get scrap data (latest run payload)')
+    .description('Get scrap data (last persisted run — read-only, no quota). Use --fresh to launch a new run instead.')
     .option('--json', 'Output as JSON')
     .option('--errors', 'Show failure diagnostics when the last run failed')
+    .option('--fresh', 'Launch a fresh run instead of reading the last persisted payload (consumes execute quota, same as `scraps run`)')
     .action(async (id, opts) => {
     validateObjectId(id);
-    // --errors: fetch full run + fix detail via fetchRunAndFix (DRY with doctor)
+    // --errors: fetch full run + fix detail via fetchRunAndFix (DRY with doctor).
+    // Read-only: GET /api/scraps/:id + GET /api/historys/:hid, no quota, no run lock.
     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;
     }
-    const loaded = await api.get(`/api/scraps/load/${id}`);
-    const items = loaded?.result?.data;
-    if (!Array.isArray(items)) {
-        console.log(chalk.dim('No data yet. Run the scrap first.'));
+    // #70 — --fresh is the explicit opt-in for a LIVE run. This is what the
+    // default path used to do silently: GET /api/scraps/load/:id executes a
+    // fresh scrap run server-side (requireQuota('scraps','execute') + a
+    // distributed run lock — trawl_node modules/scraps/routes/scraps.routes.js),
+    // 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 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;
+        }
+        renderScrapItems(items, opts.json);
         return;
     }
-    if (opts.json)
-        return json(items);
-    console.log(chalk.bold('Last run data:'));
-    console.log(chalk.dim(`  Items: ${items.length}`));
-    if (items.length > 0 && typeof items[0] === 'object' && items[0] !== null) {
-        console.log(chalk.dim(`  First item keys: ${Object.keys(items[0]).join(', ')}`));
+    // Default: read the last PERSISTED run payload — no quota, no run lock.
+    // History.data (trawl_node modules/historys/services/historys.service.js
+    // `update()`) is a JSON-stringified clone of the worker result, so it
+    // carries the same `.data` items array the live load endpoint returns —
+    // it's just pulled from the most recent history row instead of a fresh
+    // run. Retention keeps this only for the newest row per (scrap, status)
+    // bucket (config.trawl.keepData, default 1); older rows null it out.
+    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;
     }
-    console.log(chalk.dim('  Use --json for full output.'));
+    const detail = await api.get(`/api/historys/${hid}`);
+    let items;
+    if (typeof detail?.data === 'string' && detail.data) {
+        try {
+            items = JSON.parse(detail.data)?.data;
+        }
+        catch {
+            items = undefined;
+        }
+    }
+    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;
+    }
+    renderScrapItems(items, opts.json);
 });
 // history — list past runs for a scrap
 scraps
@@ -307,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}`);
@@ -378,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
@@ -392,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);
@@ -409,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
@@ -429,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);
 });
@@ -472,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')));
@@ -516,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
@@ -526,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
@@ -543,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;
@@ -553,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')));
 });
@@ -585,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');
@@ -629,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;
     }
@@ -648,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/commands/telemetry.js

@@ -28,16 +28,20 @@ telemetry
     const enabled = config.get('telemetry') !== false;
     const userId = config.get('telemetryUserId') || '(not yet generated)';
     const envOverride = process.env['TRAWL_TELEMETRY'] === '0';
+    const doNotTrack = process.env['DO_NOT_TRACK'] === '1';
     console.log(chalk.bold('Telemetry status'));
     console.log(chalk.dim('  State:         ') +
-        (envOverride
-            ? chalk.yellow('disabled (TRAWL_TELEMETRY=0 env var)')
-            : enabled
-                ? chalk.green('enabled')
-                : chalk.yellow('disabled')));
+        (doNotTrack
+            ? chalk.yellow('disabled (DO_NOT_TRACK=1 env var)')
+            : envOverride
+                ? chalk.yellow('disabled (TRAWL_TELEMETRY=0 env var)')
+                : enabled
+                    ? chalk.green('enabled')
+                    : chalk.yellow('disabled')));
     console.log(chalk.dim('  Telemetry ID:  ') + userId);
     console.log('');
     console.log(chalk.dim('  To opt out:'));
     console.log(chalk.dim('    trawl telemetry off'));
     console.log(chalk.dim('    TRAWL_TELEMETRY=0  (env var, disables for this session)'));
+    console.log(chalk.dim('    DO_NOT_TRACK=1     (cross-tool env var, disables for this session)'));
 });

package/dist/commands/token.js

@@ -1,25 +1,7 @@
 import { Command } from 'commander';
 import chalk from 'chalk';
 import config from '../lib/config.js';
-/**
- * Decode the exp claim from a JWT (middle segment, base64url encoded JSON).
- * Returns null if the payload cannot be decoded or has no exp field.
- */
-function decodeExp(jwt) {
-    try {
-        const parts = jwt.split('.');
-        if (parts.length !== 3)
-            return null;
-        const payload = Buffer.from(parts[1], 'base64url').toString('utf8');
-        const parsed = JSON.parse(payload);
-        if (typeof parsed.exp !== 'number')
-            return null;
-        return parsed.exp;
-    }
-    catch {
-        return null;
-    }
-}
+import { decodeExp } from '../lib/jwt.js';
 export const token = new Command('token')
     .description('Print the stored session JWT (for MCP Bearer auth)')
     .action(() => {
@@ -47,11 +29,15 @@ export const token = new Command('token')
         const daysLeft = secsLeft / 86400;
         if (daysLeft < 1) {
             const hoursLeft = Math.floor(secsLeft / 3600);
-            console.log(chalk.yellow(`⚠ Token expiring in ${hoursLeft}h. Run: trawl login to refresh.`));
+            // stderr, not stdout — this is an advisory, not the payload. `trawl
+            // token` exists so callers can capture the raw JWT via
+            // `$(trawl token)` for `Authorization: Bearer …`; anything printed
+            // to stdout after the token corrupts that capture. (#68)
+            console.error(chalk.yellow(`⚠ Token expiring in ${hoursLeft}h. Run: trawl login to refresh.`));
         }
         else {
             const daysRounded = Math.floor(daysLeft);
-            console.log(chalk.dim(`  Expires in ${daysRounded}d. Renew with: trawl login`));
+            console.error(chalk.dim(`  Expires in ${daysRounded}d. Renew with: trawl login`));
         }
     }
 });

package/dist/index.d.ts

@@ -1,2 +1,20 @@
 #!/usr/bin/env node
-export {};
+import { Command } from 'commander';
+/**
+ * Derive a safe telemetry event name from a *resolved* commander Command —
+ * NEVER from raw argv. Flag values (e.g. the string after --password/--email/
+ * --url) don't start with '-' and would otherwise survive an argv filter and
+ * leak to PostHog (#67). Falls back to 'unknown' when no command resolved
+ * (e.g. an error thrown before any action ran).
+ */
+export declare function resolveCommandName(actionCommand: Command | undefined): string;
+/**
+ * Walk the full command tree and produce every valid resolveCommandName()
+ * token — the allowlist registered with posthog.ts so captureCommand can
+ * never be handed a free-form string.
+ */
+export declare function collectCommandNames(root: Command): string[];
+export declare function createProgram(): Command;
+/** True when this module is the process entrypoint (not merely imported by a test). */
+export declare function isEntryPoint(argv1: string | undefined, moduleUrl: string): boolean;
+export declare function runCli(argv?: string[]): Promise<void>;