@trawlme/cli 0.1.0

package/README.md

@@ -0,0 +1,57 @@
+# trawl-cli
+
+CLI for managing Trawl scraps from the terminal.
+
+## Install
+
+```bash
+npm install -g @trawl/cli
+```
+
+## Authentication
+
+Three methods:
+
+1. **Interactive** — `trawl login` (prompts for email and password)
+2. **Env var** — `TRAWL_TOKEN=<jwt> trawl scraps list` (CI/CD, bypasses prompt)
+3. **Token flag** — `trawl login --token <jwt>` (CI/CD, direct JWT)
+
+Custom API URL: `trawl login --url https://self-hosted.example.com`
+
+## Commands
+
+### Auth
+
+```
+trawl login [--url <url>] [--token <jwt>] [--email <email>] [--password <pass>]
+trawl logout
+```
+
+### Scraps
+
+```
+trawl scraps list [--json] [--status <success|failure|never>]
+trawl scraps get <id> [--json]
+trawl scraps create -t <title> [-u <url>] [-r <request>] [-s <scrapper>]
+trawl scraps update <id> [-t title] [-u <url>] [-r request] [-s scrapper] [--cron <expr>|--no-cron] [--alert <email>|--no-alert] [-p <json>|--params-file <path>]
+trawl scraps run <id> [--watch]
+trawl scraps trigger <id> [--watch]
+trawl scraps watch <id>
+trawl scraps data <id> [--json]
+trawl scraps rm <id> [--force]
+```
+
+### Scrap accounts
+
+```
+trawl scraps account set <id> [-u <username>] [-p <password>]
+trawl scraps account delete <id> [--force]
+trawl scraps account clear-session <id>
+trawl scraps account status <id> [--json]
+```
+
+## Environment variables
+
+| Variable      | Description                                          |
+|---------------|------------------------------------------------------|
+| `TRAWL_TOKEN` | JWT token — bypasses login prompt, useful for CI/CD |

package/dist/commands/login.d.ts

@@ -0,0 +1,3 @@
+import { Command } from 'commander';
+export declare const login: Command;
+export declare const logout: Command;

package/dist/commands/login.js

@@ -0,0 +1,74 @@
+import { Command } from 'commander';
+import chalk from 'chalk';
+import config from '../lib/config.js';
+import { api } from '../lib/api.js';
+import { requireJwt, requireUrl } from '../lib/validate.js';
+import { promptPassword } from '../lib/prompt.js';
+async function promptEmail() {
+    const { createInterface } = await import('readline');
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        return await new Promise((resolve) => {
+            rl.question('Email: ', (answer) => resolve(answer.trim()));
+        });
+    }
+    finally {
+        rl.close();
+    }
+}
+export const login = new Command('login')
+    .description('Authenticate with the Trawl API')
+    .option('-u, --url <url>', 'API base URL')
+    .option('-t, --token <token>', 'JWT token (for CI use only)')
+    .option('-e, --email <email>', 'Email address')
+    .option('-p, --password <password>', 'Password (CI only — visible in process list and shell history)')
+    .action(async (opts) => {
+    if (opts.url)
+        config.set('apiUrl', requireUrl(opts.url, '--url'));
+    // Check environment variable override first
+    const envToken = process.env['TRAWL_TOKEN'];
+    if (envToken) {
+        config.set('token', requireJwt(envToken, 'TRAWL_TOKEN'));
+        console.log(chalk.green('✓ Logged in'));
+        console.log(chalk.dim(`  API: ${config.get('apiUrl')}`));
+        console.log(chalk.dim(`  Config: ${config.path}`));
+        return;
+    }
+    // --token flag: direct JWT (CI / retrocompat)
+    if (opts.token) {
+        config.set('token', requireJwt(opts.token, '--token'));
+        console.log(chalk.green('✓ Logged in'));
+        console.log(chalk.dim(`  API: ${config.get('apiUrl')}`));
+        console.log(chalk.dim(`  Config: ${config.path}`));
+        return;
+    }
+    // Email/password flow
+    if (opts.password) {
+        console.warn(chalk.yellow('Warning: passing --password on the command line is insecure.'));
+    }
+    const email = opts.email ?? (await promptEmail());
+    const password = opts.password ?? (await promptPassword('Password: '));
+    const { data, headers } = await api.publicPost('/api/auth/signin', { email, password });
+    // Try token from response body first, then fall back to Set-Cookie header
+    let raw = typeof data === 'string' ? data : data.token;
+    if (!raw) {
+        const setCookie = headers.get('set-cookie') ?? '';
+        const match = /(?:^|,\s*)TOKEN=([^;,]+)/.exec(setCookie);
+        if (match)
+            raw = decodeURIComponent(match[1]);
+    }
+    if (!raw || typeof raw !== 'string') {
+        throw new Error(`Invalid response from API: no token received. Got: ${JSON.stringify(data)}`);
+    }
+    const token = requireJwt(raw, 'token');
+    config.set('token', token);
+    console.log(chalk.green(`✓ Logged in as ${email}`));
+    console.log(chalk.dim(`  API: ${config.get('apiUrl')}`));
+    console.log(chalk.dim(`  Config: ${config.path}`));
+});
+export const logout = new Command('logout')
+    .description('Clear stored credentials')
+    .action(() => {
+    config.set('token', '');
+    console.log(chalk.green('✓ Logged out'));
+});

package/dist/commands/scraps.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare const scraps: Command;

package/dist/commands/scraps.js

@@ -0,0 +1,428 @@
+import { Command } from 'commander';
+import chalk from 'chalk';
+import ora 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';
+function lastStatus(scrap) {
+    const last = scrap.history?.[0];
+    if (!last || last.status === null || last.status === undefined)
+        return 'never';
+    return last.status === true ? 'success' : 'failure';
+}
+function lastRun(scrap) {
+    const last = scrap.history?.[0];
+    if (!last?.createdAt)
+        return '—';
+    const d = new Date(last.createdAt);
+    const dd = String(d.getDate()).padStart(2, '0');
+    const mm = String(d.getMonth() + 1).padStart(2, '0');
+    const yy = String(d.getFullYear()).slice(2);
+    const hh = String(d.getHours()).padStart(2, '0');
+    const min = String(d.getMinutes()).padStart(2, '0');
+    return `${dd}/${mm}/${yy} ${hh}:${min}`;
+}
+function statusIcon(status) {
+    if (status === 'success')
+        return chalk.green('✓');
+    if (status === 'failure')
+        return chalk.red('✗');
+    return chalk.dim('—');
+}
+export const scraps = new Command('scraps').description('Manage scraps');
+// shared SSE streaming helper
+async function watchActivities(id) {
+    console.log(chalk.dim('Streaming activities (Ctrl+C to stop)…\n'));
+    for await (const event of api.stream(`/api/scraps/${id}/activities/stream`)) {
+        try {
+            const activity = JSON.parse(event);
+            const time = new Date(activity.createdAt).toLocaleTimeString();
+            console.log(`${chalk.dim(`[${time}]`)} ${activity.message}`);
+        }
+        catch {
+            // non-JSON lines are heartbeats or SSE comments — skip silently
+            if (process.env['DEBUG'] && event.trim()) {
+                console.error(chalk.dim(`[SSE] skipping non-JSON: ${event}`));
+            }
+        }
+    }
+}
+// list
+scraps
+    .command('list')
+    .alias('ls')
+    .description('List all scraps')
+    .option('--json', 'Output as JSON')
+    .option('--status <status>', 'Filter by last run status (success|failure|never)')
+    .action(async (opts) => {
+    const spinner = ora('Fetching scraps…').start();
+    const data = await api.get('/api/scraps');
+    spinner.stop();
+    let rows = data;
+    if (opts.status)
+        rows = rows.filter((s) => lastStatus(s) === opts.status);
+    if (opts.json)
+        return json(rows);
+    const tableRows = rows.map((s) => ({
+        id: s._id,
+        title: s.title || '(untitled)',
+        cron: s.cron || '—',
+        status: statusIcon(lastStatus(s)),
+        'last run': lastRun(s),
+        updated: new Date(s.updatedAt).toLocaleDateString(),
+    }));
+    table(tableRows, ['id', 'title', 'cron', 'status', 'last run', 'updated']);
+});
+// get
+scraps
+    .command('get <id>')
+    .description('Get scrap details')
+    .option('--json', 'Output as JSON')
+    .action(async (id, opts) => {
+    validateObjectId(id);
+    const data = await api.get(`/api/scraps/${id}`);
+    if (opts.json)
+        return json(data);
+    console.log(chalk.bold(data.title || '(untitled)'));
+    console.log(chalk.dim(`  ID:       `) + data._id);
+    console.log(chalk.dim(`  Cron:     `) + (data.cron || '—'));
+    console.log(chalk.dim(`  Status:   `) + statusIcon(lastStatus(data)));
+    console.log(chalk.dim(`  Last run: `) + lastRun(data));
+    console.log(chalk.dim(`  Updated:  `) + new Date(data.updatedAt).toLocaleString());
+});
+// create
+scraps
+    .command('create')
+    .description('Create a new scrap')
+    .requiredOption('-t, --title <title>', 'Scrap title')
+    .option('-u, --url <url>', 'Target URL')
+    .option('-r, --request <request>', 'Request/query')
+    .option('-s, --scrapper <scrapper>', 'Scrapper type', 'puppeteer')
+    .action(async (opts) => {
+    const spinner = ora('Creating scrap…').start();
+    const data = await api.post('/api/scraps', {
+        title: opts.title,
+        ...(opts.url && { url: opts.url }),
+        request: opts.request || '',
+        scrapper: opts.scrapper,
+    });
+    spinner.succeed(`Scrap created: ${chalk.bold(data._id)}`);
+    console.log(chalk.dim(`  Title: ${data.title}`));
+});
+// update
+scraps
+    .command('update <id>')
+    .description('Update an existing scrap')
+    .option('-t, --title <title>', 'New title')
+    .option('-u, --url <url>', 'New target URL')
+    .option('-r, --request <request>', 'New request')
+    .option('-s, --scrapper <scrapper>', 'New scrapper type')
+    .option('--cron <expression>', 'Cron expression (empty string to disable)')
+    .option('--no-cron', 'Disable cron (set to null)')
+    .option('--alert <email>', 'Failure alert email (empty string to clear)')
+    .option('--no-alert', 'Disable failure alert email (set to null)')
+    .option('-p, --params <json>', 'Runtime params as JSON array of objects (e.g. \'[{"@slug":"..."}]\')')
+    .option('--params-file <path>', 'Runtime params from a JSON file')
+    .action(async (id, opts) => {
+    validateObjectId(id);
+    const body = {};
+    if (opts.title !== undefined)
+        body.title = opts.title;
+    if (opts.url !== undefined)
+        body.url = opts.url;
+    if (opts.request !== undefined)
+        body.request = opts.request;
+    if (opts.scrapper !== undefined)
+        body.scrapper = opts.scrapper;
+    if (opts.cron === false)
+        body.cron = null;
+    else if (typeof opts.cron === 'string')
+        body.cron = opts.cron === '' ? null : opts.cron;
+    if (opts.alert === false)
+        body.alert = null;
+    else if (typeof opts.alert === 'string')
+        body.alert = opts.alert === '' ? null : opts.alert;
+    if (opts.params !== undefined || opts.paramsFile !== undefined) {
+        let raw;
+        if (opts.paramsFile) {
+            const { readFileSync } = await import('fs');
+            raw = readFileSync(opts.paramsFile, 'utf8');
+        }
+        else {
+            raw = opts.params;
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch (e) {
+            console.log(chalk.red(`✗ Invalid JSON for --params: ${e.message}`));
+            process.exitCode = 1;
+            return;
+        }
+        if (!Array.isArray(parsed)) {
+            console.log(chalk.red('✗ --params must be a JSON array of objects'));
+            process.exitCode = 1;
+            return;
+        }
+        body.params = parsed;
+    }
+    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)}`);
+    for (const key of Object.keys(body)) {
+        console.log(chalk.dim(`  ${key}: `) + String(data[key] ?? '—'));
+    }
+});
+// run
+scraps
+    .command('run <id>')
+    .description('Run a scrap')
+    .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');
+    if (opts.watch) {
+        await watchActivities(id);
+    }
+});
+// data
+scraps
+    .command('data <id>')
+    .description('Get scrap data (latest history)')
+    .option('--json', 'Output as JSON')
+    .action(async (id, opts) => {
+    validateObjectId(id);
+    const scrap = await api.get(`/api/scraps/${id}`);
+    const lastHistory = scrap.history?.[0];
+    if (!lastHistory) {
+        console.log(chalk.dim('No data yet. Run the scrap first.'));
+        return;
+    }
+    if (opts.json)
+        return json(lastHistory);
+    const items = lastHistory.items;
+    console.log(chalk.bold('Last run data:'));
+    console.log(chalk.dim(`  Items: ${Array.isArray(items) ? items.length : '—'}`));
+    console.log(chalk.dim('  Use --json for full output.'));
+});
+// delete
+scraps
+    .command('delete <id>')
+    .alias('rm')
+    .description('Delete a scrap')
+    .option('-f, --force', 'Skip confirmation prompt')
+    .action(async (id, opts) => {
+    validateObjectId(id);
+    if (!opts.force) {
+        const { createInterface } = await import('readline');
+        const rl = createInterface({ input: process.stdin, output: process.stdout });
+        let answer;
+        try {
+            answer = await new Promise((resolve) => {
+                rl.question(`Delete scrap ${chalk.bold(id)}? ${chalk.dim('[y/N]')} `, (a) => resolve(a.trim().toLowerCase()));
+            });
+        }
+        finally {
+            rl.close();
+        }
+        if (answer !== 'y' && answer !== 'yes') {
+            console.log(chalk.dim('Aborted.'));
+            return;
+        }
+    }
+    const spinner = ora('Deleting…').start();
+    await api.delete(`/api/scraps/${id}`);
+    spinner.succeed('Scrap deleted');
+});
+// banner
+scraps
+    .command('banner <id>')
+    .description('Upload a banner image for a scrap')
+    .requiredOption('-f, --file <path>', 'Path to image file (jpg, png, webp)')
+    .action(async (id, opts) => {
+    validateObjectId(id);
+    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;
+        return;
+    }
+    const fileBuffer = readFileSync(opts.file);
+    const filename = basename(opts.file);
+    const ext = filename.split('.').pop()?.toLowerCase() ?? '';
+    const mimeMap = {
+        png: 'image/png',
+        jpg: 'image/jpeg',
+        jpeg: 'image/jpeg',
+        webp: 'image/webp',
+    };
+    const mimeType = mimeMap[ext] ?? 'image/png';
+    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)}`);
+});
+// watch (stream activities)
+scraps
+    .command('watch <id>')
+    .description('Stream scrap activities in real-time')
+    .action(async (id) => {
+    validateObjectId(id);
+    await watchActivities(id);
+});
+// trigger
+scraps
+    .command('trigger <id>')
+    .description('Launch a scrap as a background worker')
+    .option('-w, --watch', 'Stream activities after triggering')
+    .action(async (id, opts) => {
+    validateObjectId(id);
+    const spinner = ora('Triggering worker…').start();
+    await api.post(`/api/scraps/worker/${id}`);
+    spinner.succeed('Worker triggered');
+    if (opts.watch)
+        await watchActivities(id);
+});
+// account subcommand group
+const account = scraps
+    .command('account')
+    .description('Manage scrap account credentials and session');
+// helper: prompt for a value with readline (visible input)
+async function promptLine(prompt) {
+    const { createInterface } = await import('readline');
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        return await new Promise((resolve) => {
+            rl.question(prompt, (answer) => resolve(answer.trim()));
+        });
+    }
+    finally {
+        rl.close();
+    }
+}
+// account set
+account
+    .command('set <id>')
+    .description('Set credentials for a scrap account')
+    .option('-u, --username <username>', 'Account username')
+    .option('-p, --password <password>', 'Account password (insecure: prefer interactive prompt)')
+    .action(async (id, opts) => {
+    validateObjectId(id);
+    let username = opts.username || '';
+    let password = opts.password || '';
+    if (opts.password) {
+        console.log(chalk.yellow('⚠ Passing --password on the command line is insecure and may be stored in shell history.'));
+    }
+    if (!username) {
+        username = await promptLine('Username: ');
+        if (!username) {
+            console.log(chalk.red('✗ Username is required.'));
+            process.exitCode = 1;
+            return;
+        }
+    }
+    if (!password) {
+        password = await promptPassword('Password: ');
+        if (!password) {
+            console.log(chalk.red('✗ Password is required.'));
+            process.exitCode = 1;
+            return;
+        }
+    }
+    const spinner = ora('Saving credentials…').start();
+    const data = await api.put(`/api/scraps/${id}/account`, { username, password });
+    spinner.succeed('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')));
+});
+// account delete
+account
+    .command('delete <id>')
+    .description('Delete account credentials for a scrap')
+    .option('-f, --force', 'Skip confirmation prompt')
+    .action(async (id, opts) => {
+    validateObjectId(id);
+    if (!opts.force) {
+        const { createInterface } = await import('readline');
+        const rl = createInterface({ input: process.stdin, output: process.stdout });
+        let answer;
+        try {
+            answer = await new Promise((resolve) => {
+                rl.question(`Delete account credentials for scrap ${chalk.bold(id)}? ${chalk.dim('[y/N]')} `, (a) => resolve(a.trim().toLowerCase()));
+            });
+        }
+        finally {
+            rl.close();
+        }
+        if (answer !== 'y' && answer !== 'yes') {
+            console.log(chalk.dim('Aborted.'));
+            return;
+        }
+    }
+    const spinner = ora('Deleting credentials…').start();
+    await api.delete(`/api/scraps/${id}/account`);
+    spinner.succeed('Account credentials deleted');
+});
+// account clear-session
+account
+    .command('clear-session <id>')
+    .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');
+});
+// account status
+account
+    .command('status <id>')
+    .description('Show account credentials and session status for a scrap')
+    .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 acc = data.account;
+    if (opts.json) {
+        const { json: jsonFn } = await import('../lib/format.js');
+        return jsonFn(acc ?? null);
+    }
+    if (!acc) {
+        console.log(chalk.dim('No account data available.'));
+        return;
+    }
+    const credLine = acc.hasCredentials
+        ? chalk.green('✓ Credentials configured')
+        : chalk.dim('✗ No credentials');
+    let sessionLine;
+    if (acc.hasSession) {
+        if (acc.sessionSavedAt) {
+            const savedAt = new Date(acc.sessionSavedAt);
+            const diffMs = Date.now() - savedAt.getTime();
+            const diffH = Math.floor(diffMs / 1000 / 60 / 60);
+            const diffM = Math.floor((diffMs / 1000 / 60) % 60);
+            const ago = diffH > 0 ? `${diffH}h ago` : `${diffM}m ago`;
+            sessionLine = chalk.green(`✓ Session active (saved ${ago})`);
+        }
+        else {
+            sessionLine = chalk.green('✓ Session active');
+        }
+    }
+    else {
+        sessionLine = chalk.dim('✗ No active session');
+    }
+    console.log(`${credLine} | ${sessionLine}`);
+});

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import chalk from 'chalk';
+import { login, logout } from './commands/login.js';
+import { scraps } from './commands/scraps.js';
+const program = new Command()
+    .name('trawl')
+    .description('Trawl CLI — manage scraps from the terminal')
+    .version('0.1.0')
+    .option('--debug', 'Show full error stack traces');
+program.addCommand(login);
+program.addCommand(logout);
+program.addCommand(scraps);
+program.parseAsync().catch((err) => {
+    const { debug } = program.opts();
+    if (debug || process.env['DEBUG']) {
+        console.error(err);
+    }
+    else {
+        console.error(chalk.red('✗ ' + err.message));
+    }
+    process.exitCode = 1;
+});

package/dist/lib/api.d.ts

@@ -0,0 +1,12 @@
+export declare const api: {
+    get: <T>(path: string) => Promise<T>;
+    post: <T>(path: string, body?: unknown) => Promise<T>;
+    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<{
+        data: T;
+        headers: Headers;
+    }>;
+    stream: (path: string) => AsyncGenerator<string>;
+};

package/dist/lib/api.js

@@ -0,0 +1,176 @@
+import config from './config.js';
+class ApiError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+        this.name = 'ApiError';
+    }
+}
+function extractErrorMessage(raw) {
+    if (!raw)
+        return '';
+    try {
+        const parsed = JSON.parse(raw);
+        if (parsed && typeof parsed === 'object') {
+            const env = parsed;
+            const nested = typeof env.error === 'string' ? env.error : null;
+            if (nested) {
+                try {
+                    const inner = JSON.parse(nested);
+                    const details = inner.details;
+                    if (details && typeof details.message === 'string')
+                        return details.message;
+                    if (typeof inner.message === 'string')
+                        return inner.message;
+                }
+                catch {
+                    return nested;
+                }
+            }
+            if (typeof env.message === 'string')
+                return env.message;
+        }
+    }
+    catch {
+        // not JSON — fall through
+    }
+    return raw;
+}
+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);
+        if (res.status === 401 && isPublic) {
+            throw new ApiError(401, `Invalid credentials${message ? `: ${message}` : ''}`);
+        }
+        throw new ApiError(res.status, `${res.status} ${res.statusText}: ${message}`);
+    }
+}
+async function request(path, options = {}) {
+    const token = config.get('token');
+    if (!token)
+        throw new Error('Not logged in. Run: trawl login');
+    const url = `${config.get('apiUrl')}${path}`;
+    const res = await fetch(url, {
+        ...options,
+        headers: {
+            'Content-Type': 'application/json',
+            ...options.headers,
+            Cookie: `TOKEN=${token}`,
+        },
+    });
+    await throwIfError(res);
+    const text = await res.text();
+    try {
+        if (!text)
+            return {};
+        const parsed = JSON.parse(text);
+        // Unwrap API envelope { type, message, data: T }
+        if (parsed !== null && typeof parsed === 'object' && 'data' in parsed) {
+            return parsed.data;
+        }
+        return parsed;
+    }
+    catch {
+        throw new Error('Invalid JSON in server response');
+    }
+}
+async function upload(path, formData) {
+    const token = config.get('token');
+    if (!token)
+        throw new Error('Not logged in. Run: trawl login');
+    const url = `${config.get('apiUrl')}${path}`;
+    // Do NOT set Content-Type — fetch sets it automatically with the correct multipart boundary
+    const res = await fetch(url, {
+        method: 'POST',
+        body: formData,
+        headers: {
+            Cookie: `TOKEN=${token}`,
+        },
+    });
+    await throwIfError(res);
+    const text = await res.text();
+    try {
+        if (!text)
+            return {};
+        const parsed = JSON.parse(text);
+        // Unwrap API envelope { type, message, data: T }
+        if (parsed !== null && typeof parsed === 'object' && 'data' in parsed) {
+            return parsed.data;
+        }
+        return parsed;
+    }
+    catch {
+        throw new Error('Invalid JSON in server response');
+    }
+}
+async function publicPost(path, body) {
+    const url = `${config.get('apiUrl')}${path}`;
+    const res = await fetch(url, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: body ? JSON.stringify(body) : undefined,
+    });
+    await throwIfError(res, true);
+    const text = await res.text();
+    try {
+        const data = text ? JSON.parse(text) : {};
+        return { data, headers: res.headers };
+    }
+    catch {
+        throw new Error('Invalid JSON in server response');
+    }
+}
+export const api = {
+    get: (path) => request(path),
+    post: (path, body) => request(path, {
+        method: 'POST',
+        body: body ? JSON.stringify(body) : undefined,
+    }),
+    put: (path, body) => request(path, {
+        method: 'PUT',
+        body: body ? JSON.stringify(body) : undefined,
+    }),
+    delete: (path) => request(path, { method: 'DELETE' }),
+    upload: (path, formData) => upload(path, formData),
+    publicPost: (path, body) => publicPost(path, body),
+    stream: async function* (path) {
+        const token = config.get('token');
+        if (!token)
+            throw new Error('Not logged in. Run: trawl login');
+        const url = `${config.get('apiUrl')}${path}`;
+        const res = await fetch(url, {
+            headers: {
+                Accept: 'text/event-stream',
+                Cookie: `TOKEN=${token}`,
+            },
+        });
+        if (!res.ok || !res.body) {
+            throw new ApiError(res.status, `SSE failed: ${res.status}`);
+        }
+        const reader = res.body.getReader();
+        const decoder = new TextDecoder();
+        let buffer = '';
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            buffer += decoder.decode(value, { stream: true });
+            const lines = buffer.split('\n');
+            buffer = lines.pop() ?? '';
+            for (const line of lines) {
+                if (line.startsWith('data: ')) {
+                    yield line.slice(6);
+                }
+            }
+        }
+        // Flush any remaining data in buffer (stream ended without trailing newline)
+        if (buffer.startsWith('data: ')) {
+            yield buffer.slice(6);
+        }
+    },
+};

package/dist/lib/config.d.ts

@@ -0,0 +1,7 @@
+import Conf from 'conf';
+interface TrawlConfig {
+    apiUrl: string;
+    token: string;
+}
+declare const config: Conf<TrawlConfig>;
+export default config;

package/dist/lib/config.js

@@ -0,0 +1,9 @@
+import Conf from 'conf';
+const config = new Conf({
+    projectName: 'trawl-cli',
+    defaults: {
+        apiUrl: 'https://api.trawl.me',
+        token: '',
+    },
+});
+export default config;

package/dist/lib/format.d.ts

@@ -0,0 +1,2 @@
+export declare function table(rows: Record<string, unknown>[], columns: string[]): void;
+export declare function json(data: unknown): void;

package/dist/lib/format.js

@@ -0,0 +1,25 @@
+import chalk from 'chalk';
+import stripAnsi from 'strip-ansi';
+export function table(rows, columns) {
+    if (!rows.length) {
+        console.log(chalk.dim('No results.'));
+        return;
+    }
+    const widths = columns.map((col) => Math.max(col.length, ...rows.map((r) => stripAnsi(String(r[col] ?? '')).length)));
+    const header = columns.map((col, i) => chalk.bold(col.padEnd(widths[i]))).join('  ');
+    console.log(header);
+    console.log(chalk.dim('─'.repeat(header.replace(/\x1b\[[0-9;]*m/g, '').length)));
+    for (const row of rows) {
+        const line = columns
+            .map((col, i) => {
+            const raw = String(row[col] ?? '');
+            const visLen = stripAnsi(raw).length;
+            return raw + ' '.repeat(Math.max(0, widths[i] - visLen));
+        })
+            .join('  ');
+        console.log(line);
+    }
+}
+export function json(data) {
+    console.log(JSON.stringify(data, null, 2));
+}

package/dist/lib/prompt.d.ts

@@ -0,0 +1 @@
+export declare function promptPassword(prompt: string): Promise<string>;

package/dist/lib/prompt.js

@@ -0,0 +1,44 @@
+export async function promptPassword(prompt) {
+    process.stderr.write(prompt);
+    return new Promise((resolve) => {
+        let password = '';
+        if (process.stdin.isTTY) {
+            process.stdin.setRawMode(true);
+            process.stdin.resume();
+            process.stdin.setEncoding('utf8');
+            const onData = (char) => {
+                if (char === '\r' || char === '\n') {
+                    process.stdin.setRawMode(false);
+                    process.stdin.pause();
+                    process.stdin.removeListener('data', onData);
+                    process.stderr.write('\n');
+                    resolve(password);
+                }
+                else if (char === '\u0003') {
+                    // Ctrl+C
+                    process.stdin.setRawMode(false);
+                    process.stdin.pause();
+                    process.exit(1);
+                }
+                else if (char === '\u007F' || char === '\b') {
+                    // Backspace
+                    password = password.slice(0, -1);
+                }
+                else {
+                    password += char;
+                }
+            };
+            process.stdin.on('data', onData);
+        }
+        else {
+            // Non-TTY fallback (e.g. piped input in CI)
+            import('readline').then(({ createInterface }) => {
+                const rl = createInterface({ input: process.stdin, output: process.stdout });
+                rl.question('', (answer) => {
+                    rl.close();
+                    resolve(answer.trim());
+                });
+            });
+        }
+    });
+}

package/dist/lib/validate.d.ts

@@ -0,0 +1,4 @@
+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;

package/dist/lib/validate.js

@@ -0,0 +1,33 @@
+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`);
+    }
+}
+export function requireString(value, name) {
+    if (typeof value !== 'string' || value.trim() === '') {
+        throw new Error(`${name} is required and must be a non-empty string`);
+    }
+    return value.trim();
+}
+export function requireUrl(value, name) {
+    const str = requireString(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`);
+        }
+    }
+    catch (err) {
+        if (err instanceof Error && err.message.startsWith(name))
+            throw err;
+        throw new Error(`${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`);
+    }
+    return str;
+}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@trawlme/cli",
+  "version": "0.1.0",
+  "description": "Trawl CLI — manage scraps from the terminal",
+  "type": "module",
+  "bin": {
+    "trawl": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "dev": "tsc --watch",
+    "start": "node dist/index.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "snapshot:spec": "node scripts/snapshot-spec.mjs"
+  },
+  "keywords": [
+    "trawl",
+    "scraping",
+    "cli"
+  ],
+  "author": "Pierre Brisorgueil",
+  "license": "ISC",
+  "dependencies": {
+    "chalk": "^5.6.2",
+    "commander": "^14.0.3",
+    "conf": "^15.1.0",
+    "ora": "^9.3.0",
+    "strip-ansi": "^7.2.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.2",
+    "@vitest/coverage-v8": "^4.1.2",
+    "typescript": "^6.0.2",
+    "vitest": "^4.1.2"
+  }
+}