@trawlme/cli 1.16.0 → 1.18.0

package/dist/lib/posthog.js

@@ -1,4 +1,5 @@
 import { PostHog } from 'posthog-node';
+import chalk from 'chalk';
 import os from 'node:os';
 import crypto from 'node:crypto';
 import { readFileSync } from 'node:fs';
@@ -8,26 +9,66 @@ import config from './config.js';
 // public-by-design — cf memory feedback_public_keys_in_config.md
 const POSTHOG_KEY = 'phc_pGgSLivbq8rDZzXC9trWWJG7sBjNghXeTJjETzBcnEDv';
 const POSTHOG_HOST = 'https://eu.i.posthog.com';
+// Fail fast: a firewalled/offline endpoint must never add tens of seconds of
+// trailing latency to a CLI command. Library defaults are requestTimeout 10s x
+// 3 retries at a 3s delay (~40s+ worst case per call), and a 30s shutdown
+// ceiling on top of that — cap all three low.
+const REQUEST_TIMEOUT_MS = 3000;
+const FETCH_RETRY_COUNT = 1;
+const FETCH_RETRY_DELAY_MS = 250;
+// A touch above one request + one retry, so the shutdown-time flush has room
+// to complete normally without inheriting the library's 30s default ceiling.
+const SHUTDOWN_TIMEOUT_MS = 8000;
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(resolve(__dirname, '../../package.json'), 'utf8'));
 let client = null;
 let distinctId = null;
+let allowedCommands = new Set();
+/**
+ * Cross-vendor opt-out (https://consoledonottrack.com) on top of the existing
+ * config/env gates. Any one of these disables telemetry entirely.
+ */
+function isTelemetryDisabled() {
+    return (config.get('telemetry') === false ||
+        process.env['TRAWL_TELEMETRY'] === '0' ||
+        process.env['DO_NOT_TRACK'] === '1');
+}
 export const initPostHog = () => {
-    if (config.get('telemetry') === false || process.env['TRAWL_TELEMETRY'] === '0')
+    if (isTelemetryDisabled())
         return;
-    if (!config.get('telemetryUserId')) {
+    const isFirstRun = !config.get('telemetryUserId');
+    if (isFirstRun) {
         config.set('telemetryUserId', `cli_${crypto.randomUUID()}`);
+        // One-time disclosure — telemetry is on by default and otherwise silent.
+        console.error(chalk.dim('ℹ Trawl CLI collects anonymous usage telemetry (no credentials or command arguments). ' +
+            'Opt out: trawl telemetry off, TRAWL_TELEMETRY=0, or DO_NOT_TRACK=1.'));
     }
     distinctId = config.get('telemetryUserId');
     client = new PostHog(POSTHOG_KEY, {
         host: POSTHOG_HOST,
         flushAt: 1,
         flushInterval: 0,
+        requestTimeout: REQUEST_TIMEOUT_MS,
+        fetchRetryCount: FETCH_RETRY_COUNT,
+        fetchRetryDelay: FETCH_RETRY_DELAY_MS,
     });
 };
+/**
+ * Register the complete set of valid "<parent> <name>" telemetry tokens,
+ * derived from the actual commander command tree (see resolveCommandName /
+ * collectCommandNames in src/index.ts). captureCommand refuses any command
+ * string outside this set — defense in depth so free-form user input (argv
+ * operands, flag values) can never reach PostHog as the event name, even if a
+ * future change accidentally reintroduces argv-derived naming.
+ */
+export const registerAllowedCommands = (names) => {
+    allowedCommands = new Set(names);
+};
 export const captureCommand = (command, props = {}) => {
     if (!client || !distinctId)
         return;
+    if (!allowedCommands.has(command))
+        return;
     client.capture({
         distinctId,
         event: 'cli.command.run',
@@ -42,11 +83,14 @@ export const captureCommand = (command, props = {}) => {
     });
 };
 export const shutdown = async () => {
+    // Explicit ceiling — client.shutdown() otherwise defaults to a 30s internal
+    // race, which would undercut the whole point of capping request/retry time.
     if (client)
-        await client.shutdown();
+        await client.shutdown(SHUTDOWN_TIMEOUT_MS);
 };
 /** Reset singleton state — for testing only */
 export const _resetForTesting = () => {
     client = null;
     distinctId = null;
+    allowedCommands = new Set();
 };

package/dist/lib/prompt.js

@@ -1,6 +1,6 @@
 export async function promptPassword(prompt) {
     process.stderr.write(prompt);
-    return new Promise((resolve) => {
+    return new Promise((resolve, reject) => {
         let password = '';
         if (process.stdin.isTTY) {
             process.stdin.setRawMode(true);
@@ -31,13 +31,24 @@ export async function promptPassword(prompt) {
             process.stdin.on('data', onData);
         }
         else {
-            // Non-TTY fallback (e.g. piped input in CI)
+            // Non-TTY fallback (e.g. piped input in CI). If stdin closes (EOF)
+            // before an answer arrives — e.g. `trawl login < /dev/null` — the
+            // `question` callback never fires; without a `close` handler the
+            // promise hangs forever and the process exits 0 without logging in.
+            // Reject loudly instead. (#68)
             import('readline').then(({ createInterface }) => {
                 const rl = createInterface({ input: process.stdin, output: process.stdout });
+                let answered = false;
                 rl.question('', (answer) => {
+                    answered = true;
                     rl.close();
                     resolve(answer.trim());
                 });
+                rl.on('close', () => {
+                    if (!answered) {
+                        reject(new Error('No input received — pass -e/-p or set TRAWL_TOKEN for non-interactive use'));
+                    }
+                });
             });
         }
     });

package/dist/lib/validate.d.ts

@@ -2,3 +2,12 @@ export declare function validateObjectId(id: string): void;
 export declare function requireString(value: unknown, name: string): string;
 export declare function requireUrl(value: unknown, name: string): string;
 export declare function requireJwt(value: unknown, name: string): string;
+/**
+ * Like requireJwt, but also rejects a JWT whose `exp` claim has already
+ * passed — `trawl login --token <expired>` / `TRAWL_TOKEN=<expired>` must
+ * not print "✓ Logged in" for a token that can't actually authenticate.
+ * A JWT with an undecodable/opaque payload is let through (we can't prove
+ * it's expired), mirroring `trawl token`'s advisory-only handling of the
+ * same case. (#68)
+ */
+export declare function requireFreshJwt(value: unknown, name: string): string;

package/dist/lib/validate.js

@@ -1,11 +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();
 }
@@ -14,20 +16,37 @@ 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;
 }
+/**
+ * Like requireJwt, but also rejects a JWT whose `exp` claim has already
+ * passed — `trawl login --token <expired>` / `TRAWL_TOKEN=<expired>` must
+ * not print "✓ Logged in" for a token that can't actually authenticate.
+ * A JWT with an undecodable/opaque payload is let through (we can't prove
+ * it's expired), mirroring `trawl token`'s advisory-only handling of the
+ * same case. (#68)
+ */
+export function requireFreshJwt(value, name) {
+    const jwt = requireJwt(value, name);
+    const exp = decodeExp(jwt);
+    const nowSeconds = Math.floor(Date.now() / 1000);
+    if (exp !== null && exp < nowSeconds) {
+        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.16.0",
+  "version": "1.18.0",
   "description": "Trawl CLI — manage scraps from the terminal",
   "type": "module",
   "bin": {
@@ -12,7 +12,7 @@
     "LICENSE"
   ],
   "engines": {
-    "node": ">=18"
+    "node": ">=20"
   },
   "scripts": {
     "build": "tsc",