@trawlme/cli 2.0.0 → 2.1.1

package/README.md

@@ -37,7 +37,8 @@ All commands accept a global `--debug` flag to show full error stack traces on f
 ### Core commands (agent + human)
 
 ```
-trawl create <url> --prompt <goal> [--no-autofix] [--json]   Create a persistent, self-healing scrap from a URL + a goal (AI-generated)
+trawl create <url> --prompt <goal> [--no-autofix] [--json]   # url also accepted as --url <url> (#116)
+                                                              Create a persistent, self-healing scrap from a URL + a goal (AI-generated)
 trawl run <id> [--watch] [--json]              Run a scrap
 trawl list|ls [--json] [--status <success|failure|never|running|regression>] [--limit <n>] [--page <n>]
 trawl get <id> [--json]                        Get scrap details

package/dist/commands/create.js

@@ -1,9 +1,10 @@
 import { Command } from 'commander';
 import chalk from 'chalk';
-import { oraPromise } from 'ora';
+import { spin } from '../lib/spinner.js';
 import { api, LONG_RUN_TIMEOUT_MS, NetworkError } from '../lib/api.js';
 import { json } from '../lib/format.js';
 import { requireUrl, requireString } from '../lib/validate.js';
+import { UsageError } from '../lib/errors.js';
 /** Best-effort, honest first-run summary — never claims a background retry
  * happened when auto-fix was disabled for this call, and never claims a
  * scrap was persisted when the response carries none (#114-F3 — a hard
@@ -51,15 +52,28 @@ function scheduleLabel(scrap) {
 }
 export const create = new Command('create')
     .description('Create a persistent, self-healing scrap from a URL + a goal (AI-generated)')
-    .argument('<url>', 'Target public URL (http/https)')
-    .requiredOption('--prompt <goal>', 'What to extract/scrape, in plain language')
+    .argument('[url]', 'Target public URL (http/https)')
+    .requiredOption('--prompt <goal>', 'What to extract/scrape, in plain language (required)')
+    .option('--url <url>', 'Target public URL — alias of the positional argument')
     .option('--no-autofix', 'Disable AI auto-fix on first-run failure (default: on)')
     .option('--json', 'Output the raw API payload')
     .action(async (rawUrl, opts) => {
     // Fast, local usage-errors (exit 2) — never a round-trip to the server
     // for something we can already tell is bad. Same fail-fast pattern the
     // former `fetch` command used for its URL argument.
-    const url = requireUrl(rawUrl, 'url');
+    //
+    // #116 — the url is accepted BOTH as the positional argument (agent
+    // one-liner) and as `--url` (muscle memory from `scraps create` and the
+    // API body {url, goal}). Exactly one is required; both are fine only
+    // when identical — two DIFFERENT urls is ambiguous, refuse loudly
+    // rather than silently picking one.
+    if (rawUrl === undefined && opts.url === undefined) {
+        throw new UsageError("missing required argument 'url' (positional, or --url <url>)");
+    }
+    if (rawUrl !== undefined && opts.url !== undefined && rawUrl !== opts.url) {
+        throw new UsageError(`conflicting urls: positional "${rawUrl}" vs --url "${opts.url}" — pass only one`);
+    }
+    const url = requireUrl(rawUrl ?? opts.url, 'url');
     const goal = requireString(opts.prompt, '--prompt');
     const body = {
         url,
@@ -81,7 +95,7 @@ export const create = new Command('create')
     }
     else {
         try {
-            data = await oraPromise(call, {
+            data = await spin(call, {
                 text: `Creating a scrap from ${url}…`,
                 // No verdict symbol here (#106-F3) — ora's success only means "the
                 // HTTP call didn't throw", not "the first run succeeded". The real

package/dist/commands/doctor.js

@@ -1,5 +1,6 @@
 import { api } from '../lib/api.js';
 import chalk from 'chalk';
+import { formatDate } from '../lib/format.js';
 /**
  * Known anti-bot vendors (+ auth) that the worker's `blockType` field may name.
  * Ordered by first-match; `blockType` is a freeform worker string, not an enum
@@ -142,7 +143,7 @@ export function formatDoctor(scrapTitle, run, fix = null, scrapId) {
     }
     // Timestamp
     if (run.createdAt) {
-        lines.push(chalk.dim('  Run at:  ') + new Date(run.createdAt).toLocaleString());
+        lines.push(chalk.dim('  Run at:  ') + formatDate(run.createdAt));
     }
     // Snapshot hint
     if (run.errorSnapshot?.html || run.statusDetail === 'empty' || run.statusDetail === 'error') {

package/dist/commands/ping.js

@@ -17,7 +17,9 @@ export const ping = new Command('ping')
         json(data);
         return;
     }
-    const versionSuffix = data.version ? ` (v${data.version})` : '';
+    // #119 — label it as the API's version, not a bare `v0.4.0` that reads as
+    // "the platform is v0.4" (it's the server package version field).
+    const versionSuffix = data.version ? ` (api v${data.version})` : '';
     if (data.status === 'ok') {
         console.log(chalk.green('✓ OK') + versionSuffix);
     }

package/dist/commands/scraps.js

@@ -1,8 +1,8 @@
 import { Command } from 'commander';
 import chalk from 'chalk';
-import { oraPromise } from 'ora';
+import { spin } from '../lib/spinner.js';
 import { api, LONG_RUN_TIMEOUT_MS } from '../lib/api.js';
-import { table, json } from '../lib/format.js';
+import { table, json, formatDate } from '../lib/format.js';
 import { promptPassword } from '../lib/prompt.js';
 import { validateObjectId } from '../lib/validate.js';
 import { classifyError, reportError, UsageError, RefusalError } from '../lib/errors.js';
@@ -42,16 +42,7 @@ function lastStatus(scrap) {
     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}`;
+    return formatDate(scrap.history?.[0]?.createdAt); // #119 — unified DD/MM/YY HH:mm
 }
 function statusIcon(status) {
     if (status === 'success')
@@ -389,7 +380,7 @@ export function attachListCommand(parent, attachOpts = {}) {
         }
         let data;
         try {
-            data = await oraPromise(async () => {
+            data = await spin(async () => {
                 if (page !== undefined) {
                     // Single-page mode: explicit page requested, no loop
                     return api.get(`/api/scraps?perPage=50&page=${page}`);
@@ -445,7 +436,7 @@ export function attachListCommand(parent, attachOpts = {}) {
             cron: s.cron || '—',
             status: statusIcon(lastStatus(s)),
             'last run': lastRun(s),
-            updated: new Date(s.updatedAt).toLocaleDateString(),
+            updated: formatDate(s.updatedAt),
         }));
         table(tableRows, ['id', 'title', 'cron', 'status', 'last run', 'updated']);
         // Print footer when --limit truncates
@@ -471,7 +462,7 @@ export function attachGetCommand(parent, attachOpts = {}) {
         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());
+        console.log(chalk.dim(`  Updated:  `) + formatDate(data.updatedAt));
     });
 }
 attachGetCommand(scraps, { hidden: true });
@@ -566,7 +557,7 @@ scraps
         usageError(`Invalid --tier "${opts.tier}" (allowed: ${VALID_TIERS.join(', ')})`, { json: opts.json });
         return;
     }
-    const data = await oraPromise(() => api.post('/api/scraps', {
+    const data = await spin(() => api.post('/api/scraps', {
         title: opts.title,
         ...(opts.url && { url: opts.url }),
         request: opts.request || '',
@@ -681,7 +672,7 @@ scraps
         console.log(chalk.yellow('Nothing to update. Provide at least one option.'));
         return;
     }
-    const data = await oraPromise(() => api.put(`/api/scraps/${id}`, body), {
+    const data = await spin(() => api.put(`/api/scraps/${id}`, body), {
         text: 'Updating scrap…',
         successText: (d) => `Scrap updated: ${chalk.bold(d._id)}`,
     });
@@ -735,7 +726,7 @@ export function attachRunCommand(parent, attachOpts = {}) {
         // all, mirroring `trawl create`'s own --json handling.
         const data = opts.json
             ? await call()
-            : await oraPromise(call, { text: 'Launching scrap…', successText: 'Scrap launched' });
+            : await spin(call, { text: 'Launching scrap…', successText: 'Scrap launched' });
         if (opts.json)
             json(data);
         if (opts.watch) {
@@ -830,7 +821,7 @@ export function attachDataCommand(parent, attachOpts = {}) {
         if (opts.fresh) {
             // #91 P0 — same long-run endpoint as `run` (30-250s server-side);
             // the 30s default was aborting it mid-flight.
-            const loaded = await oraPromise(() => api.get(`/api/scraps/load/${id}`, { timeoutMs: LONG_RUN_TIMEOUT_MS }), {
+            const loaded = await spin(() => api.get(`/api/scraps/load/${id}`, { timeoutMs: LONG_RUN_TIMEOUT_MS }), {
                 text: 'Launching a fresh scrap run (consumes execute quota)…',
                 successText: 'Fresh run complete',
             });
@@ -1050,7 +1041,7 @@ scraps
         json({ deleted: true, id });
         return;
     }
-    await oraPromise(call, { text: 'Deleting…', successText: 'Scrap deleted' });
+    await spin(call, { text: 'Deleting…', successText: 'Scrap deleted' });
 });
 // banner
 scraps
@@ -1092,7 +1083,7 @@ scraps
         json(data);
         return;
     }
-    await oraPromise(call, {
+    await spin(call, {
         text: 'Uploading banner…',
         successText: `Banner uploaded for scrap ${chalk.bold(id)}`,
     });
@@ -1135,7 +1126,7 @@ export function attachTriggerCommand(parent, attachOpts = {}) {
         // #107 — under --json the stdout path stays pure: no spinner channel.
         const data = opts.json
             ? await call()
-            : await oraPromise(call, {
+            : await spin(call, {
                 text: opts.wait ? 'Running worker…' : 'Triggering worker…',
                 successText: opts.wait ? 'Worker run complete' : 'Worker triggered',
             });
@@ -1214,7 +1205,7 @@ account
         json(data);
         return;
     }
-    const data = await oraPromise(call, { text: 'Saving credentials…', successText: 'Credentials saved' });
+    const data = await spin(call, { 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')));
@@ -1244,7 +1235,7 @@ account
         json({ deleted: true, id });
         return;
     }
-    await oraPromise(call, {
+    await spin(call, {
         text: 'Deleting credentials…',
         successText: 'Account credentials deleted',
     });
@@ -1262,7 +1253,7 @@ account
         json({ cleared: true, id });
         return;
     }
-    await oraPromise(call, {
+    await spin(call, {
         text: 'Clearing session…',
         successText: 'Session cleared',
     });
@@ -1311,7 +1302,7 @@ accountSession
         json(data);
         return;
     }
-    const data = await oraPromise(call, {
+    const data = await spin(call, {
         text: 'Uploading session cookies…',
         successText: `Session cookies saved for scrap ${chalk.bold(id)}`,
     });
@@ -1325,7 +1316,7 @@ account
     .option('--json', 'Output as JSON')
     .action(async (id, opts) => {
     validateObjectId(id);
-    const data = await oraPromise(() => api.get(`/api/scraps/${id}`), 'Fetching scrap…');
+    const data = await spin(() => api.get(`/api/scraps/${id}`), 'Fetching scrap…');
     const acc = data.account;
     if (opts.json) {
         // #86 finding 12 — `json` is already statically imported at the top of

package/dist/lib/format.d.ts

@@ -1,2 +1,9 @@
 export declare function table(rows: Record<string, unknown>[], columns: string[]): void;
 export declare function json(data: unknown): void;
+/**
+ * One date format across the whole CLI: `DD/MM/YY HH:mm` (local time).
+ * #119 — `list` mixed `DD/MM/YY` (last-run col) with `M/D/YYYY,
+ * h:mm:ss AM/PM` (toLocaleString), ambiguous day/month side by side.
+ * Returns `—` for a missing/invalid date.
+ */
+export declare function formatDate(value: string | number | Date | null | undefined): string;

package/dist/lib/format.js

@@ -23,3 +23,22 @@ export function table(rows, columns) {
 export function json(data) {
     console.log(JSON.stringify(data, null, 2));
 }
+/**
+ * One date format across the whole CLI: `DD/MM/YY HH:mm` (local time).
+ * #119 — `list` mixed `DD/MM/YY` (last-run col) with `M/D/YYYY,
+ * h:mm:ss AM/PM` (toLocaleString), ambiguous day/month side by side.
+ * Returns `—` for a missing/invalid date.
+ */
+export function formatDate(value) {
+    if (value === null || value === undefined)
+        return '—';
+    const d = new Date(value);
+    if (Number.isNaN(d.getTime()))
+        return '—';
+    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}`;
+}

package/dist/lib/spinner.d.ts

@@ -0,0 +1,18 @@
+type Action<T> = PromiseLike<T> | (() => PromiseLike<T>);
+type SpinOptions<T> = string | {
+    text?: string;
+    successText?: string | ((result: T) => string);
+    failText?: string | ((error: Error) => string);
+    [key: string]: unknown;
+};
+/**
+ * Drop-in for `oraPromise` that emits NOTHING when stderr is not a TTY.
+ *
+ * #119 — under a pipe / non-TTY, `oraPromise` still printed the start text AND
+ * a persisted `✔ …` line, so `trawl list | cat` showed the spinner caption
+ * twice. An agent/CI never wants spinner chrome; here we just run the action.
+ * When stderr IS a TTY, behaviour is identical to `oraPromise` (spinner writes
+ * to stderr, stdout stays clean either way).
+ */
+export declare function spin<T>(action: Action<T>, options?: SpinOptions<T>): Promise<T>;
+export {};

package/dist/lib/spinner.js

@@ -0,0 +1,17 @@
+import { oraPromise } from 'ora';
+/**
+ * Drop-in for `oraPromise` that emits NOTHING when stderr is not a TTY.
+ *
+ * #119 — under a pipe / non-TTY, `oraPromise` still printed the start text AND
+ * a persisted `✔ …` line, so `trawl list | cat` showed the spinner caption
+ * twice. An agent/CI never wants spinner chrome; here we just run the action.
+ * When stderr IS a TTY, behaviour is identical to `oraPromise` (spinner writes
+ * to stderr, stdout stays clean either way).
+ */
+export function spin(action, options) {
+    if (!process.stderr.isTTY) {
+        return Promise.resolve(typeof action === 'function' ? action() : action);
+    }
+    // oraPromise's own overloads accept (action, string) and (action, options).
+    return oraPromise(action, options);
+}

package/docs/agent-quickstart.md

@@ -25,7 +25,8 @@ first-class on every one, and none of them ever blocks on a prompt (see
 [Non-interactive contract](#non-interactive-contract) below):
 
 ```
-trawl create <url> --prompt <goal> [--no-autofix] [--json]   Create a persistent, self-healing scrap from a URL + a goal (AI-generated)
+trawl create <url> --prompt <goal> [--no-autofix] [--json]   # url also accepted as --url <url> (#116)
+                                                              Create a persistent, self-healing scrap from a URL + a goal (AI-generated)
 trawl run <id> [--watch] [--json]              Run a scrap
 trawl list|ls [--json] [--status <s>] [--limit <n>] [--page <n>]   List all scraps
 trawl get <id> [--json]                        Get scrap details

package/package.json

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