@trawlme/cli 1.18.1 → 1.18.3

package/README.md

@@ -10,6 +10,8 @@ Command-line client for [Trawl](https://trawl.me) — manage your scraps from th
 
 ## Install
 
+Requires Node.js >= 20.
+
 ```bash
 npm install -g @trawlme/cli
 ```
@@ -41,8 +43,8 @@ trawl token                                  Print the stored session JWT (for M
 ```
 trawl scraps list [--json] [--status <success|failure|never>] [--limit <n>] [--page <n>]
 trawl scraps get <id> [--json]
-trawl scraps create -t <title> [-u <url>] [-r <request>] [-d <description>] [--tier <tier0|tier1|tier2|tier3|tier4>]
-trawl scraps update <id> [-t <title>] [-u <url>] [-r <request>] [-d <description>] [--cron <expr>|--no-cron] [--alert <email>|--no-alert] [--autofix|--no-autofix] [-p <json>|--params-file <path>] [--tier <tier0|tier1|tier2|tier3|tier4>] [--force-tier <tier0|tier1|tier2|tier3|tier4>]
+trawl scraps create -t <title> [-u <url>] [-r <request>] [-d <description>] [--tier <tier0|tier1|tier2|tier3|tier4>] [--json]
+trawl scraps update <id> [-t <title>] [-u <url>] [-r <request>] [-d <description>] [--cron <expr>|--no-cron] [--alert <email>|--no-alert] [--autofix|--no-autofix] [-p <json>|--params-file <path>] [--tier <tier0|tier1|tier2|tier3|tier4>] [--force-tier <tier0|tier1|tier2|tier3|tier4>] [--json]
 trawl scraps run <id> [--watch]
 trawl scraps trigger <id> [--watch] [--wait]
 trawl scraps watch <id>
@@ -53,15 +55,16 @@ trawl scraps doctor <id> [--json] [--autofix]
 trawl scraps autofix <id> [--json]
 trawl scraps snapshot <id> [--error] [-o <file>]
 trawl scraps banner <id> -f <file>
-trawl scraps rm <id> [--force]
+trawl scraps delete <id> [--force]         Alias: rm
 ```
 
-- `--tier` forces a proxy tier; `--force-tier` raises the proxy-tier ceiling past the auto-cap (history-gated: may be refused or cost more).
-- `scraps doctor` diagnoses the last run (error, failed selector, block status, page state, autofix outcome); `--autofix` includes the full autofix diff/dry-run/knowledge.
-- `scraps autofix` shows the last auto-fix attempt on its own (decision, diff, dry-run, knowledge).
+- `--tier` forces a proxy tier; `--force-tier` raises the proxy-tier ceiling past the auto-cap (history-gated: may be refused or cost more). `create --json`/`update --json` print the full scrap object (including the `_tierOverride` outcome) on stdout; a refused tier override exits 1 with a standard `--json` error envelope. When a tier was requested but the server's response carries no `_tierOverride` at all (an older server that can't confirm what actually got applied), a stderr warning is printed either way, and under `--json` the emitted object also carries `"_tierUnconfirmed": true` — the machine-readable counterpart to that warning, since a `--json` caller has no reliable reason to read stderr.
+- `scraps doctor` diagnoses the last run (error, failed selector, block status, page state, autofix outcome); `--autofix` includes the full autofix diff/dry-run/knowledge. A run that is still in flight (`status: null`, server-side) shows a `running` badge, never `failed`.
+- `scraps autofix` shows the last auto-fix attempt on its own (decision, diff, dry-run, knowledge). `--json` on a scrap that has **never run** returns `{"status":"no_runs"}` (exit 0) — distinct from `null`, which means a run exists but had no auto-fix attempt.
 - `scraps snapshot --error` fetches the error-path snapshot instead of the normal one; `-o <file>` writes to a file instead of stdout.
 - `scraps history` lists past runs (newest first); `scraps run-info <hid>` shows details of a single run from that history.
-- `scraps data` returns the last persisted run payload (no execute quota); `--fresh` runs the scrap live instead (consumes execute quota); `--errors` shows the last run's error detail.
+- `scraps data` returns the last persisted run payload (no execute quota); `--fresh` runs the scrap live instead (consumes execute quota); `--errors` shows the last run's error detail (`--json` on a never-run scrap returns `{"status":"no_runs"}`, exit 0, matching `doctor --json`). `[]` on stdout means a genuine zero-item successful run — a scrap that has never run, whose last run failed, or whose payload aged out of retention returns a `--json` error envelope (exit 4/1/4 respectively) instead. Two more honest states: a run still **in flight** (`status: null` server-side) returns a `kind:"in_progress"` error envelope (exit 1, "retry shortly" — never suggests `--fresh`, which would just 429 against the run already holding the lock); a run whose item count **regressed** vs baseline (`statusDetail: "regression"`) still returns the real, non-empty items on stdout (exit 0) plus a stderr warning pointing at `scraps doctor <id>` — the data itself is genuine even though the run is flagged.
+- `scraps get` (and anything reading through it, like `scraps data`'s default path) embeds only the newest 100 history rows on the returned scrap object — `scraps run-info` and `scraps doctor` fetch a single run directly and are unaffected by that cap.
 
 ### Scrap accounts
 
@@ -80,13 +83,15 @@ trawl scraps account session set <id> -c <file>
 The CLI bundles a Claude Code skill that teaches Claude how to use `trawl`. Once installed, Claude can manage scraps for you via prompts.
 
 ```
-trawl skills list                            List bundled skills and install status
-trawl skills install [<skill>] [--local]     Install all (or one). Default: ~/.claude/skills/
-trawl skills uninstall [<skill>] [--local]   Remove
-trawl skills update [<skill>] [--local]      Reinstall (force sync with CLI version)
+trawl skills list                                     List bundled skills and install status
+trawl skills install [<skill>] [--local] [--force]    Install all (or one). Default: ~/.claude/skills/
+trawl skills uninstall [<skill>] [--local]            Remove
+trawl skills update [<skill>] [--local] [--force]     Reinstall (force sync with CLI version)
 ```
 
-Skills auto-update silently when you upgrade the CLI — no need to re-install manually.
+Skills auto-update when you upgrade the CLI — no need to re-install manually — but it is not silent: it prints an honest `trawl: re-synced skill "<name>" (<scope>) <old> → <new>` line to stderr whenever it rewrites a skill dir, so a rewrite is never invisible. If a bundled skill is renamed or dropped between CLI versions, the old install is swept too — a `trawl: removed orphaned skill "<name>" (<scope>) — no longer bundled with this CLI version` line to stderr, so a stale skill teaching outdated CLI usage never lingers silently. Only marker-owned dirs (installed by trawl itself) are ever touched by either line. Opt out with `TRAWL_SKILLS_SYNC=0`.
+
+A pre-existing skill directory that trawl did not install itself (no `.version` marker) is never touched — `install`/`update` refuse to overwrite it and require `--force` to proceed. This applies to the CLI-upgrade auto-sync too (it silently skips marker-less dirs rather than refusing, since there is no interactive user to show a refusal to).
 
 You can also install skills standalone (without the CLI): `npx @trawlme/skills install`.
 
@@ -108,7 +113,7 @@ trawl telemetry status   Show current state, telemetry ID, and opt-out instructi
 - Node.js version
 - Platform (e.g. `darwin`, `linux`, `win32`)
 - Command duration (`duration_ms`)
-- Exit code (`0` = success, `1` = error)
+- Exit code — the full 0–5 range below, not just success/failure (see [Exit codes](#exit-codes))
 - Error name if the command failed (e.g. `ApiError`) — never the error message or stack
 - An opaque, randomly-generated telemetry ID (`cli_<uuid>`) stored locally in your config file
 
@@ -131,13 +136,32 @@ TRAWL_TELEMETRY=0 trawl scraps list
 
 **Why:** usage data helps us prioritise CLI features and catch silent errors before users report them.
 
+## Exit codes
+
+Every command exits with one of these codes — scripts and agents driving the CLI unattended can branch on the exact failure kind instead of a uniform pass/fail:
+
+| Code | Meaning                                                                 |
+|------|--------------------------------------------------------------------------|
+| `0`  | Success                                                                 |
+| `1`  | Unknown/generic error (an unmapped failure — API errors other than 401/404, an unhandled bug — or a business-logic refusal like `scraps data`'s `run_failed`/`in_progress` states) |
+| `2`  | Usage error (bad flag/value, invalid ID, missing required argument, unknown option/command) |
+| `3`  | Auth error (not logged in, or the session token is expired/invalid — run `trawl login`) |
+| `4`  | Not found (no such resource, or — for `scraps data` — no persisted payload to read) |
+| `5`  | Network error (the API host is unreachable, DNS/connection/TLS failure, or the request timed out) |
+
+Under `--json`, a failing command emits a single error envelope on stdout — `{"error":{"message","status?","kind"}}` — instead of prose; the human-readable line always goes to stderr, never stdout.
+
 ## Environment variables
 
-| Variable           | Description                                                       |
-|--------------------|-------------------------------------------------------------------|
-| `TRAWL_TOKEN`      | JWT token — bypasses login prompt, useful for CI/CD               |
-| `TRAWL_API_URL`    | Override the API base URL for the session (takes precedence over `trawl login --url`) |
-| `TRAWL_TELEMETRY`  | Set to `0` to disable telemetry for the current session           |
+| Variable             | Description                                                       |
+|-----------------------|--------------------------------------------------------------------|
+| `TRAWL_TOKEN`         | JWT token — bypasses login prompt, useful for CI/CD               |
+| `TRAWL_API_URL`       | Override the API base URL for the session (takes precedence over `trawl login --url`) |
+| `TRAWL_TELEMETRY`     | Set to `0` to disable telemetry for the current session           |
+| `DO_NOT_TRACK`        | Set to `1` to disable telemetry (cross-vendor convention, https://consoledonottrack.com) — same effect as `TRAWL_TELEMETRY=0` |
+| `TRAWL_CONFIG_DIR`    | Override where the config file (token, API URL, telemetry state) is stored — useful for hermetic CI runs or concurrent `trawl login`s that must not share one on-disk file |
+| `TRAWL_TIMEOUT`       | Override the per-request fetch timeout in milliseconds (default `30000`) |
+| `TRAWL_SKILLS_SYNC`   | Set to `0` to disable the startup skills auto-sync entirely       |
 
 Session override (no `trawl login` mutation, ideal for CI/QA against another env):
 

package/dist/commands/doctor.js

@@ -83,13 +83,17 @@ export function pickFix(fix) {
  */
 export function formatDoctor(scrapTitle, run, fix = null, scrapId) {
     const lines = [];
-    // Header + status badge
+    // Header + status badge. status:null means a run is IN FLIGHT (node
+    // persists {status:null, statusDetail:null, inFlight:true} the moment a
+    // run starts) — that must never render as "failed". (#88 item 1)
     const ok = run.status === true;
     const badge = ok
         ? chalk.green('● success')
-        : run.statusDetail === 'empty'
-            ? chalk.yellow('● empty')
-            : chalk.red('● failed');
+        : run.status === null
+            ? chalk.cyan('● running')
+            : run.statusDetail === 'empty'
+                ? chalk.yellow('● empty')
+                : chalk.red('● failed');
     lines.push(`${chalk.bold(scrapTitle)}  ${badge}${run.statusDetail ? ` (${run.statusDetail})` : ''}`);
     lines.push(chalk.dim(`  Run ID:  ${run._id}`));
     // Error message — an honest accept-wall string for known-walled scraps