@trawlme/cli 1.16.0 → 1.18.0

package/dist/index.js

@@ -2,7 +2,7 @@
 import { Command } from 'commander';
 import chalk from 'chalk';
 import { readFileSync } from 'node:fs';
-import { fileURLToPath } from 'node:url';
+import { fileURLToPath, pathToFileURL } from 'node:url';
 import { dirname, join } from 'node:path';
 import { login, logout } from './commands/login.js';
 import { scraps } from './commands/scraps.js';
@@ -10,49 +10,120 @@ import { skills } from './commands/skills.js';
 import { telemetry } from './commands/telemetry.js';
 import { token } from './commands/token.js';
 import { autoUpdateInstalledSkills } from './lib/skills.js';
-import { initPostHog, captureCommand, shutdown } from './lib/posthog.js';
-autoUpdateInstalledSkills();
-initPostHog();
+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'));
-const program = new Command()
-    .name('trawl')
-    .description('Trawl CLI — manage scraps from the terminal')
-    .version(pkg.version)
-    .option('--debug', 'Show full error stack traces');
-// Track start times per command instance for duration measurement
-const startTimes = new WeakMap();
-program.hook('preAction', (thisCommand, actionCommand) => {
-    startTimes.set(actionCommand, Date.now());
-});
-program.hook('postAction', (thisCommand, actionCommand) => {
-    const start = startTimes.get(actionCommand);
-    if (start !== undefined) {
-        const name = actionCommand.parent
-            ? `${actionCommand.parent.name()} ${actionCommand.name()}`
-            : actionCommand.name();
-        void captureCommand(name, { duration_ms: Date.now() - start, exit_code: 0 });
+/**
+ * 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 function resolveCommandName(actionCommand) {
+    if (!actionCommand)
+        return 'unknown';
+    return actionCommand.parent
+        ? `${actionCommand.parent.name()} ${actionCommand.name()}`
+        : actionCommand.name();
+}
+/**
+ * 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 function collectCommandNames(root) {
+    const names = [];
+    const walk = (cmd) => {
+        for (const sub of cmd.commands) {
+            names.push(resolveCommandName(sub));
+            walk(sub);
+        }
+    };
+    walk(root);
+    return names;
+}
+export function createProgram() {
+    const program = new Command()
+        .name('trawl')
+        .description('Trawl CLI — manage scraps from the terminal')
+        .version(pkg.version)
+        .option('--debug', 'Show full error stack traces');
+    program.addCommand(login);
+    program.addCommand(logout);
+    program.addCommand(scraps);
+    program.addCommand(skills);
+    program.addCommand(telemetry);
+    program.addCommand(token);
+    return program;
+}
+/** True when this module is the process entrypoint (not merely imported by a test). */
+export function isEntryPoint(argv1, moduleUrl) {
+    return argv1 !== undefined && moduleUrl === pathToFileURL(argv1).href;
+}
+export async function runCli(argv = process.argv) {
+    autoUpdateInstalledSkills();
+    initPostHog();
+    const program = createProgram();
+    registerAllowedCommands(collectCommandNames(program));
+    // Track start times + the currently-resolved command per instance, so the
+    // catch handler below can derive the exact same safe name the success path
+    // uses — it must never re-derive anything from argv.
+    const startTimes = new WeakMap();
+    let currentCommand;
+    program.hook('preAction', (_thisCommand, actionCommand) => {
+        currentCommand = actionCommand;
+        startTimes.set(actionCommand, Date.now());
+    });
+    program.hook('postAction', (_thisCommand, actionCommand) => {
+        const start = startTimes.get(actionCommand);
+        if (start !== undefined) {
+            // Actions can fail without throwing (process.exitCode set directly) —
+            // report the real outcome instead of hardcoding success.
+            const exitCode = typeof process.exitCode === 'number' ? process.exitCode : 0;
+            void captureCommand(resolveCommandName(actionCommand), {
+                duration_ms: Date.now() - start,
+                exit_code: exitCode,
+            });
+        }
+    });
+    try {
+        await program.parseAsync(argv);
     }
-});
-program.addCommand(login);
-program.addCommand(logout);
-program.addCommand(scraps);
-program.addCommand(skills);
-program.addCommand(telemetry);
-program.addCommand(token);
-process.on('exit', () => {
-    void shutdown();
-});
-program.parseAsync().catch((err) => {
-    // Capture error telemetry (best-effort: command name from process.argv)
-    const name = process.argv.slice(2).filter((a) => !a.startsWith('-')).join(' ') || 'unknown';
-    void captureCommand(name, { exit_code: 1, error: err.name });
-    const { debug } = program.opts();
-    if (debug || process.env['DEBUG']) {
-        console.error(err);
+    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: exitCode,
+            error: err.name,
+        });
+        const { debug } = program.opts();
+        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 if (!isDebug) {
+            console.error(chalk.red('✗ ' + envelope.message));
+        }
+        process.exitCode = exitCode;
     }
-    else {
-        console.error(chalk.red('✗ ' + err.message));
+    finally {
+        // Flush + close telemetry before the process exits. A `process.on('exit')`
+        // handler cannot reliably run async work, so this must happen here.
+        await shutdown();
     }
-    process.exitCode = 1;
-});
+}
+if (isEntryPoint(process.argv[1], import.meta.url)) {
+    void runCli();
+}

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>;
@@ -5,7 +18,7 @@ export declare const api: {
     put: <T>(path: string, body?: unknown) => Promise<T>;
     delete: <T>(path: string) => Promise<T>;
     upload: <T>(path: string, formData: FormData) => Promise<T>;
-    publicPost: <T>(path: string, body?: unknown) => Promise<{
+    publicPost: <T>(path: string, body?: unknown, baseUrlOverride?: string) => Promise<{
         data: T;
         headers: Headers;
     }>;

package/dist/lib/api.js

@@ -1,11 +1,11 @@
 import { readFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { dirname, resolve } from 'node:path';
-import config, { getApiUrl } from './config.js';
+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,26 +100,77 @@ 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 = {}) {
-    const token = config.get('token');
+    const token = getToken();
     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,
@@ -87,14 +195,15 @@ async function request(path, options = {}) {
     }
 }
 async function upload(path, formData) {
-    const token = config.get('token');
+    const token = getToken();
     if (!token)
         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}`,
@@ -116,12 +225,13 @@ async function upload(path, formData) {
         throw new Error('Invalid JSON in server response');
     }
 }
-async function publicPost(path, body) {
-    const url = `${getApiUrl()}${path}`;
-    const res = await fetch(url, {
+async function publicPost(path, body, baseUrlOverride) {
+    const url = `${baseUrlOverride ?? getApiUrl()}${path}`;
+    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();
@@ -134,15 +244,16 @@ async function publicPost(path, body) {
     }
 }
 async function getText(path) {
-    const token = config.get('token');
+    const token = getToken();
     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();
@@ -160,13 +271,16 @@ export const api = {
     }),
     delete: (path) => request(path, { method: 'DELETE' }),
     upload: (path, formData) => upload(path, formData),
-    publicPost: (path, body) => publicPost(path, body),
+    publicPost: (path, body, baseUrlOverride) => publicPost(path, body, baseUrlOverride),
     stream: async function* (path) {
-        const token = config.get('token');
+        const token = getToken();
         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/config.d.ts

@@ -14,4 +14,15 @@ declare const config: Conf<TrawlConfig>;
  * without mutating the operator's persisted config. (#56)
  */
 export declare function getApiUrl(): string;
+/**
+ * Resolve the effective session token.
+ * Precedence: TRAWL_TOKEN env > stored `trawl login` token.
+ * Lets CI/agents authenticate headlessly (`TRAWL_TOKEN=<jwt> trawl scraps list`)
+ * without ever touching the on-disk config — and without a stored token being
+ * silently sent to whatever TRAWL_API_URL points at instead (cross-env
+ * credential misuse). Every request/upload/getText/stream call site in
+ * api.ts must read the token through this, never through `config.get('token')`
+ * directly. Mirrors getApiUrl(). (#68)
+ */
+export declare function getToken(): string;
 export default config;

package/dist/lib/config.js

@@ -1,6 +1,16 @@
 import Conf from 'conf';
+/**
+ * TRAWL_CONFIG_DIR overrides where Conf stores the config file (its `cwd`
+ * option). Without this, the CLI has zero config isolation on macOS — Conf's
+ * env-paths dependency hardcodes `~/Library/Preferences/...` and ignores
+ * XDG_CONFIG_HOME — so CI/agent runs and concurrent `trawl login`s race on
+ * one shared on-disk file. Point at an ephemeral dir for hermetic runs, e.g.
+ * `TRAWL_CONFIG_DIR=$(mktemp -d) trawl login --token …`. Rescope of #59. (#68)
+ */
+const configDir = process.env['TRAWL_CONFIG_DIR']?.trim();
 const config = new Conf({
     projectName: 'trawl-cli',
+    ...(configDir ? { cwd: configDir } : {}),
     defaults: {
         apiUrl: 'https://api.trawl.me',
         token: '',
@@ -19,4 +29,18 @@ export function getApiUrl() {
     const override = process.env['TRAWL_API_URL']?.trim();
     return override ? override : config.get('apiUrl');
 }
+/**
+ * Resolve the effective session token.
+ * Precedence: TRAWL_TOKEN env > stored `trawl login` token.
+ * Lets CI/agents authenticate headlessly (`TRAWL_TOKEN=<jwt> trawl scraps list`)
+ * without ever touching the on-disk config — and without a stored token being
+ * silently sent to whatever TRAWL_API_URL points at instead (cross-env
+ * credential misuse). Every request/upload/getText/stream call site in
+ * api.ts must read the token through this, never through `config.get('token')`
+ * directly. Mirrors getApiUrl(). (#68)
+ */
+export function getToken() {
+    const override = process.env['TRAWL_TOKEN']?.trim();
+    return override ? override : config.get('token');
+}
 export default config;

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/jwt.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 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.
+ *
+ * Shared between `trawl token` (expiry advisory) and `trawl login` (reject
+ * already-expired tokens instead of silently storing them). (#68)
+ */
+export declare function decodeExp(jwt: string): number | null;

package/dist/lib/jwt.js

@@ -0,0 +1,22 @@
+/**
+ * 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.
+ *
+ * Shared between `trawl token` (expiry advisory) and `trawl login` (reject
+ * already-expired tokens instead of silently storing them). (#68)
+ */
+export 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;
+    }
+}

package/dist/lib/posthog.d.ts

@@ -1,4 +1,13 @@
 export declare const initPostHog: () => void;
+/**
+ * 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 declare const registerAllowedCommands: (names: readonly string[]) => void;
 export declare const captureCommand: (command: string, props?: Record<string, unknown>) => void;
 export declare const shutdown: () => Promise<void>;
 /** Reset singleton state — for testing only */