@trawlme/cli 1.21.0 → 1.22.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +44 -35
- package/dist/commands/scraps.d.ts +29 -0
- package/dist/commands/scraps.js +413 -392
- package/dist/index.d.ts +8 -0
- package/dist/index.js +45 -7
- package/docs/agent-quickstart.md +103 -0
- package/package.json +2 -1
package/README.md
CHANGED
|
@@ -8,6 +8,8 @@ Command-line client for [Trawl](https://trawl.me) — manage your scraps from th
|
|
|
8
8
|
|
|
9
9
|
> ⚠️ **Early stage.** APIs may change before `1.0`. Pin a version if you depend on this in CI.
|
|
10
10
|
|
|
11
|
+
> 🤖 **Driving this CLI from an AI agent?** See [docs/agent-quickstart.md](docs/agent-quickstart.md) for the minimal surface (`fetch`, `--json`, `TRAWL_TOKEN`, exit codes) — this README is the full human/CI guide.
|
|
12
|
+
|
|
11
13
|
## Install
|
|
12
14
|
|
|
13
15
|
Requires Node.js >= 20.
|
|
@@ -21,48 +23,50 @@ npm install -g @trawlme/cli
|
|
|
21
23
|
Three methods:
|
|
22
24
|
|
|
23
25
|
1. **Interactive** — `trawl login` (prompts for email and password)
|
|
24
|
-
2. **Env var** — `TRAWL_TOKEN=<jwt> trawl
|
|
26
|
+
2. **Env var** — `TRAWL_TOKEN=<jwt> trawl list` (CI/CD, bypasses prompt)
|
|
25
27
|
3. **Token flag** — `trawl login --token <jwt>` (CI/CD, direct JWT)
|
|
26
28
|
|
|
27
29
|
Custom API URL: `trawl login --url https://self-hosted.example.com`
|
|
28
30
|
|
|
29
31
|
## Commands
|
|
30
32
|
|
|
33
|
+
`trawl --help` groups commands into two labeled tiers, in this exact wording: **Core commands (agent + human)** (listed first — `--json` first-class, never interactive) and **Management commands (human/CI)** (grouped below — the full scrap-admin/account/auth/skills/telemetry surface). Commander also prints a small ungrouped `help [command]` entry at the bottom, so "two tiers" describes the labeled sections, not literally every line of `--help` output. This section documents both tiers, in that order; [docs/agent-quickstart.md](docs/agent-quickstart.md) covers just the Core tier for an agent integration.
|
|
34
|
+
|
|
31
35
|
All commands accept a global `--debug` flag to show full error stack traces on failure. Every command below supports `--json` (a raw payload / structured result on stdout, nothing else) and never blocks on an interactive prompt when `--json` is set or stdin/stdout isn't a real TTY — see [Non-interactive rule](#non-interactive-rule) and [Exit codes](#exit-codes). Two documented exceptions to "single payload": `scraps watch --json` is a live stream, so it emits NDJSON (one JSON object per line) instead; `scraps snapshot --json` only changes behavior on a never-run scrap (`{"status":"no_runs"}`) — when a run exists it still writes the raw HTML snapshot regardless of `--json` (there's no JSON-encoded form of an HTML page to emit).
|
|
32
36
|
|
|
33
|
-
###
|
|
37
|
+
### Core commands (agent + human)
|
|
34
38
|
|
|
35
39
|
```
|
|
36
|
-
trawl
|
|
37
|
-
trawl
|
|
38
|
-
trawl
|
|
40
|
+
trawl fetch <url> [--json] [--reason <text>] One-shot fetch + extract readable content from a public URL (no scrap needed)
|
|
41
|
+
trawl run <id> [--watch] [--json] Run a scrap
|
|
42
|
+
trawl list|ls [--json] [--status <success|failure|never|running|regression>] [--limit <n>] [--page <n>]
|
|
43
|
+
trawl get <id> [--json] Get scrap details
|
|
44
|
+
trawl data <id> [--json] [--fresh] [--errors] Get scrap data (last persisted run — read-only, no quota; --fresh to launch one)
|
|
45
|
+
trawl history <id> [--json] [-n <limit>] List past runs for a scrap (newest first)
|
|
46
|
+
trawl run-info <hid> [--json] Show details of a single run
|
|
47
|
+
trawl trigger <id> [--watch] [--wait] [--json] Launch a scrap as a background worker (returns immediately)
|
|
48
|
+
trawl whoami [--json] Show the authenticated user's identity
|
|
49
|
+
trawl ping [--json] Health/version handshake against the Trawl API
|
|
39
50
|
```
|
|
40
51
|
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
### Agent core verbs
|
|
52
|
+
> **No breaking change:** every verb above is also still reachable under its pre-reorg path, `trawl scraps <verb>` (e.g. `trawl scraps list`, `trawl scraps run <id>`) — kept as a hidden alias so scripts written before the surface reorg keep working. `trawl --help` only shows the top-level form above; `trawl scraps --help` only shows the remaining scrap-management commands below.
|
|
44
53
|
|
|
45
|
-
|
|
46
|
-
trawl fetch <url> [--json] [--reason <text>] One-shot fetch + extract readable content from a public URL (no scrap needed)
|
|
47
|
-
trawl whoami [--json] Show the authenticated user's identity
|
|
48
|
-
trawl ping [--json] Health/version handshake against the Trawl API
|
|
49
|
-
```
|
|
54
|
+
`fetch`/`whoami`/`ping` are fully non-interactive — all three read auth only from `TRAWL_TOKEN`/the stored login token, never prompt. `trawl fetch` is the REST counterpart of the MCP `trawl_fetch_url` tool (same shared engine, `POST /api/scraps/fetch-url`): `status` is an honest outcome (`completed`/`failed`/`empty`/`blocked`), not "did the HTTP call succeed" — a failed fetch is still a 200 response with `status:'failed'` + `error`, and the CLI exits 1 in that case (both human and `--json` modes) even though `--json` always prints the raw payload verbatim. `truncated:true` means the 100KB response cap tripped; `result` is dropped and `url` repoints at the full history row instead. `trawl whoami`/`trawl ping` mirror the MCP `trawl_whoami`/`trawl_health_ping` tools as closely as the REST surface allows (`GET /api/users/me` / `GET /api/health`) — `ping`'s `--json` payload is admin-enriched (version/uptime/db) and just `{"status":"ok"}` for anyone else.
|
|
50
55
|
|
|
51
|
-
|
|
56
|
+
- `list` has a short alias, `ls` (matches `trawl --help`'s `list|ls`).
|
|
57
|
+
- `history` lists past runs (newest first); `run-info <hid>` shows details of a single run from that history.
|
|
58
|
+
- `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 `scraps 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.
|
|
59
|
+
- `get` (and anything reading through it, like `data`'s default path) embeds only the newest 100 history rows on the returned scrap object — `run-info` and `scraps doctor` fetch a single run directly and are unaffected by that cap. `list`/`get` show a distinct amber `▼` "regression" badge, never the red `✗` a genuine failure gets (matches `scraps doctor`'s own badge).
|
|
60
|
+
- **Long-running scrap execute (`run`, `data --fresh`, `trigger --wait`):** these hit the same server-side scrap-execute path, which can legitimately take 30–250s (proxy tier escalation, AI-fix retries) — the CLI arms a 300s timeout for exactly these three call sites instead of the generic 30s default. `TRAWL_TIMEOUT` (see below) still overrides ALL requests, including these — set it if you need a tighter or looser ceiling than 300s for a long-running scrap.
|
|
61
|
+
- **`--watch` is poll-based, not a live stream:** the activities SSE endpoint has no backlog and, for the default async `trigger` (no `--wait`), runs in a separate cron-consumer pod whose events never reach the API pod holding the SSE connection — a naive "await the run, then open SSE" shows nothing. `run --watch` and `trigger --watch` instead poll `GET /api/scraps/:id` (terminal status) and the activities REST list until the run finishes, printing each new activity line as it appears. The watched run's outcome drives the exit code too, in BOTH human and `--json` mode: a genuinely failed terminal run, a poll timeout, or a persistently unreachable API all exit non-zero — a clean successful run is the only exit `0`. A run that never reaches a terminal status within 300s prints an honest timeout notice pointing at `scraps doctor <id>` (human mode) — see the `--json` shape below. `scraps watch <id>` (the standalone command, no trigger) is unchanged — it still opens the live SSE stream directly.
|
|
62
|
+
- `run --json`/`trigger --json` bypass the spinner and print the raw launch/trigger payload on stdout; combined with `--watch`, every intermediate progress line stays suppressed (stdout stays pure JSON) and, once the watch reaches its outcome, exactly ONE final NDJSON line is emitted: `{"runId","status"}` (the honest terminal status — `success`/`error`/`empty`/`regression`/…), `{"runId","status":"timeout"}` on a poll timeout, or `{"runId","status":"poll_error","error"}` if the API stays unreachable for several consecutive polls — `process.exitCode` is non-zero for all three except a genuine success. `scraps watch --json` emits one raw JSON object per activity line (NDJSON) instead of the formatted `[time] message` text — there's no single final payload to wait for on a live stream.
|
|
52
63
|
|
|
53
|
-
###
|
|
64
|
+
### Scrap management
|
|
54
65
|
|
|
55
66
|
```
|
|
56
|
-
trawl scraps list [--json] [--status <success|failure|never|running|regression>] [--limit <n>] [--page <n>]
|
|
57
|
-
trawl scraps get <id> [--json]
|
|
58
67
|
trawl scraps create -t <title> [-u <url>] [-r <request>] [-d <description>] [--tier <tier0|tier1|tier2|tier3|tier4>] [--json]
|
|
59
68
|
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]
|
|
60
|
-
trawl scraps run <id> [--watch] [--json]
|
|
61
|
-
trawl scraps trigger <id> [--watch] [--wait] [--json]
|
|
62
69
|
trawl scraps watch <id> [--json]
|
|
63
|
-
trawl scraps data <id> [--json] [--fresh] [--errors]
|
|
64
|
-
trawl scraps history <id> [--json] [-n <limit>]
|
|
65
|
-
trawl scraps run-info <hid> [--json]
|
|
66
70
|
trawl scraps doctor <id> [--json] [--autofix]
|
|
67
71
|
trawl scraps autofix <id> [--json]
|
|
68
72
|
trawl scraps snapshot <id> [--error] [-o <file>] [--json]
|
|
@@ -71,16 +75,11 @@ trawl scraps delete <id> [--force] [--json] Alias: rm
|
|
|
71
75
|
```
|
|
72
76
|
|
|
73
77
|
- `--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 (`kind:"refused"` — distinct from `"unknown"`, so a script can branch on "the server said no"). 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.
|
|
74
|
-
- `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`; a run whose item count regressed vs baseline (`statusDetail: "regression"`) shows its own amber `regression` badge, never `failed` either
|
|
78
|
+
- `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`; a run whose item count regressed vs baseline (`statusDetail: "regression"`) shows its own amber `regression` badge, never `failed` either.
|
|
75
79
|
- `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.
|
|
76
80
|
- `scraps snapshot --error` fetches the error-path snapshot instead of the normal one; `-o <file>` writes to a file instead of stdout. On a scrap that has **never run**: `--json` returns `{"status":"no_runs"}` (exit 0), matching `doctor`/`autofix`; `-o <file>` (without `--json`) exits 4 (`not_found`) instead of silently exiting 0 with nothing written — a script checking the exit code alone must be able to tell "no file was produced" from success. `--json` takes priority when both are passed.
|
|
77
|
-
- `scraps history` lists past runs (newest first); `scraps run-info <hid>` shows details of a single run from that history.
|
|
78
|
-
- `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.
|
|
79
|
-
- `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.
|
|
80
81
|
- `scraps banner -f <file>` only accepts `png`/`jpg`/`jpeg`/`webp`; any other extension is a usage error (exit 2) instead of silently uploading the file under a fabricated `image/png` Content-Type.
|
|
81
|
-
-
|
|
82
|
-
- **`--watch` is poll-based, not a live stream:** the activities SSE endpoint has no backlog and, for the default async `trigger` (no `--wait`), runs in a separate cron-consumer pod whose events never reach the API pod holding the SSE connection — a naive "await the run, then open SSE" shows nothing. `scraps run --watch` and `scraps trigger --watch` instead poll `GET /api/scraps/:id` (terminal status) and the activities REST list until the run finishes, printing each new activity line as it appears. The watched run's outcome drives the exit code too, in BOTH human and `--json` mode: a genuinely failed terminal run, a poll timeout, or a persistently unreachable API all exit non-zero — a clean successful run is the only exit `0`. A run that never reaches a terminal status within 300s prints an honest timeout notice pointing at `scraps doctor <id>` (human mode) — see the `--json` shape below. `scraps watch <id>` (the standalone command, no trigger) is unchanged — it still opens the live SSE stream directly.
|
|
83
|
-
- `scraps run --json`/`trigger --json` bypass the spinner and print the raw launch/trigger payload on stdout; combined with `--watch`, every intermediate progress line stays suppressed (stdout stays pure JSON) and, once the watch reaches its outcome, exactly ONE final NDJSON line is emitted: `{"runId","status"}` (the honest terminal status — `success`/`error`/`empty`/`regression`/…), `{"runId","status":"timeout"}` on a poll timeout, or `{"runId","status":"poll_error","error"}` if the API stays unreachable for several consecutive polls — `process.exitCode` is non-zero for all three except a genuine success. `scraps watch --json` emits one raw JSON object per activity line (NDJSON) instead of the formatted `[time] message` text — there's no single final payload to wait for on a live stream. `scraps delete`/`banner --json` print `{"deleted":true,"id"}` / the raw upload response.
|
|
82
|
+
- `scraps delete`/`banner --json` print `{"deleted":true,"id"}` / the raw upload response.
|
|
84
83
|
|
|
85
84
|
### Scrap accounts
|
|
86
85
|
|
|
@@ -113,6 +112,16 @@ A pre-existing skill directory that trawl did not install itself (no `.version`
|
|
|
113
112
|
|
|
114
113
|
You can also install skills standalone (without the CLI): `npx @trawlme/skills install`.
|
|
115
114
|
|
|
115
|
+
### Auth
|
|
116
|
+
|
|
117
|
+
```
|
|
118
|
+
trawl login [--url <url>] [--token <jwt>] [--email <email>] [--password <pass>] [--json]
|
|
119
|
+
trawl logout [--json]
|
|
120
|
+
trawl token [--json] Print the stored session JWT (for MCP Bearer auth)
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
`login --json` prints `{"ok":true,"apiUrl","config",email?}` on success — never the raw token (that's `token`'s job). `token --json` prints `{"token","exp","expiresAt"}` instead of the bare JWT + stderr advisories. See [Non-interactive rule](#non-interactive-rule) below: a missing `--email`/`--password` refuses immediately (usage error, exit 2) instead of prompting when `--json` is set or stdin/stdout isn't a real TTY.
|
|
124
|
+
|
|
116
125
|
### Telemetry
|
|
117
126
|
|
|
118
127
|
```
|
|
@@ -126,7 +135,7 @@ trawl telemetry status [--json] Show current state, telemetry ID, and opt-out
|
|
|
126
135
|
`@trawlme/cli` collects anonymous usage data to help us improve the CLI based on real usage patterns. Telemetry is enabled by default.
|
|
127
136
|
|
|
128
137
|
**What we collect:**
|
|
129
|
-
- Command name (e.g. `scraps
|
|
138
|
+
- Command name (e.g. `list` — the #108 surface reorg renamed a promoted verb's telemetry event from `scraps <verb>` to `<verb>`; invoking the legacy `trawl scraps <verb>` path still emits the pre-reorg `scraps <verb>` name)
|
|
130
139
|
- CLI version
|
|
131
140
|
- Node.js version
|
|
132
141
|
- Platform (e.g. `darwin`, `linux`, `win32`)
|
|
@@ -149,7 +158,7 @@ trawl telemetry status [--json] Show current state, telemetry ID, and opt-out
|
|
|
149
158
|
trawl telemetry off
|
|
150
159
|
|
|
151
160
|
# Session-level opt-out (env var, takes precedence)
|
|
152
|
-
TRAWL_TELEMETRY=0 trawl
|
|
161
|
+
TRAWL_TELEMETRY=0 trawl list
|
|
153
162
|
```
|
|
154
163
|
|
|
155
164
|
**Why:** usage data helps us prioritise CLI features and catch silent errors before users report them.
|
|
@@ -170,10 +179,10 @@ Every command exits with one of these codes — scripts and agents driving the C
|
|
|
170
179
|
| Code | Meaning |
|
|
171
180
|
|------|--------------------------------------------------------------------------|
|
|
172
181
|
| `0` | Success |
|
|
173
|
-
| `1` | Unknown/generic error (an unmapped failure — API errors other than 401/404, an unhandled bug — or a business-logic refusal like `
|
|
182
|
+
| `1` | Unknown/generic error (an unmapped failure — API errors other than 401/404, an unhandled bug — or a business-logic refusal like `data`'s `run_failed`/`in_progress` states, or `trawl fetch`'s honest `status:'failed'`/`'blocked'` outcome). **Known overload:** `fetch`'s domain-level failure and an arbitrary unmapped bug both land on `1` — a script needs to read the `--json` payload's own `status`/`error` field (for `fetch`) to tell them apart; this is intentional (the REST contract's outcome states are a separate axis from the CLI's transport-error taxonomy) and documented here rather than "resolved" by inventing a new code that would only apply to one command. |
|
|
174
183
|
| `2` | Usage error (bad flag/value, invalid ID, missing required argument, unknown option/command — including the [non-interactive rule](#non-interactive-rule) refusing to prompt) |
|
|
175
184
|
| `3` | Auth error (not logged in, or the session token is expired/invalid — run `trawl login`) |
|
|
176
|
-
| `4` | Not found (no such resource, or — for `
|
|
185
|
+
| `4` | Not found (no such resource, or — for `data` — no persisted payload to read) |
|
|
177
186
|
| `5` | Network error (the API host is unreachable, DNS/connection/TLS failure, or the request timed out) |
|
|
178
187
|
|
|
179
188
|
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. `kind` is the machine-readable discriminant (`"usage"`/`"auth"`/`"not_found"`/`"network"`/`"api"`/`"refused"`/`"unknown"`/…) — the short string a script should switch on (`"refused"` is a business-logic refusal the server explicitly reported back, e.g. `scraps create|update`'s tier-ceiling override rejection — distinct from `"unknown"`, which stays reserved for an unmapped bug); `status` is present only when a real HTTP response carried one (never fabricated for a local failure like an expired-locally JWT or a refused confirmation prompt).
|
|
@@ -187,13 +196,13 @@ Under `--json`, a failing command emits a single error envelope on stdout — `{
|
|
|
187
196
|
| `TRAWL_TELEMETRY` | Set to `0` to disable telemetry for the current session |
|
|
188
197
|
| `DO_NOT_TRACK` | Set to `1` to disable telemetry (cross-vendor convention, https://consoledonottrack.com) — same effect as `TRAWL_TELEMETRY=0` |
|
|
189
198
|
| `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 |
|
|
190
|
-
| `TRAWL_TIMEOUT` | Override the per-request fetch timeout in milliseconds (default `30000`; `300000` for `
|
|
199
|
+
| `TRAWL_TIMEOUT` | Override the per-request fetch timeout in milliseconds (default `30000`; `300000` for `run`/`data --fresh`/`trigger --wait` — this env var always wins over that longer default too) |
|
|
191
200
|
| `TRAWL_SKILLS_SYNC` | Set to `0` to disable the startup skills auto-sync entirely |
|
|
192
201
|
|
|
193
202
|
Session override (no `trawl login` mutation, ideal for CI/QA against another env):
|
|
194
203
|
|
|
195
204
|
```bash
|
|
196
|
-
TRAWL_API_URL=https://dev.trawl.me TRAWL_TOKEN=<jwt> trawl
|
|
205
|
+
TRAWL_API_URL=https://dev.trawl.me TRAWL_TOKEN=<jwt> trawl list --json
|
|
197
206
|
```
|
|
198
207
|
|
|
199
208
|
## API documentation
|
|
@@ -1,4 +1,26 @@
|
|
|
1
1
|
import { Command } from 'commander';
|
|
2
|
+
/**
|
|
3
|
+
* #108 — surface reorg. `run`/`list`/`get`/`data`/`history`/`run-info`/
|
|
4
|
+
* `trigger` are promoted to top-level verbs (see index.ts's `createProgram`)
|
|
5
|
+
* alongside `fetch`/`whoami`/`ping`. Each is built by an exported
|
|
6
|
+
* `attachXCommand(parent, attachOpts)` factory instead of a fixed
|
|
7
|
+
* `scraps.command(...)` chain, so it can be attached TWICE with a single
|
|
8
|
+
* source-of-truth definition: once to `program` (the new canonical
|
|
9
|
+
* top-level path) and once more, hidden, right back onto `scraps` — so every
|
|
10
|
+
* pre-#108 `trawl scraps <verb>` invocation keeps resolving unchanged
|
|
11
|
+
* (`{ hidden: true }` only affects help visibility, never resolution).
|
|
12
|
+
*
|
|
13
|
+
* Future-drift guard: ALL `.option()`/`.argument()`/`.action()` wiring for a
|
|
14
|
+
* promoted verb MUST live INSIDE its `attachXCommand` factory body, never
|
|
15
|
+
* bolted onto one of its two call sites (index.ts's `createProgram` for the
|
|
16
|
+
* top-level attach, this file's own `attachXCommand(scraps, { hidden: true
|
|
17
|
+
* })` call for the legacy one). That's the only thing keeping `trawl run
|
|
18
|
+
* <id>` and `trawl scraps run <id>` identical — a call-site-only tweak to
|
|
19
|
+
* one attachment would silently diverge the two.
|
|
20
|
+
*/
|
|
21
|
+
type AttachOptions = {
|
|
22
|
+
hidden?: boolean;
|
|
23
|
+
};
|
|
2
24
|
export declare const scraps: Command;
|
|
3
25
|
/** The top-of-history snapshot pollRunProgress needs to identify which run
|
|
4
26
|
* it's watching — see captureBeforeRunState.
|
|
@@ -115,4 +137,11 @@ export declare function pollRunProgress(id: string, before: BeforeRunState | und
|
|
|
115
137
|
timeoutMs?: number;
|
|
116
138
|
json?: boolean;
|
|
117
139
|
}): Promise<void>;
|
|
140
|
+
export declare function attachListCommand(parent: Command, attachOpts?: AttachOptions): Command;
|
|
141
|
+
export declare function attachGetCommand(parent: Command, attachOpts?: AttachOptions): Command;
|
|
142
|
+
export declare function attachRunCommand(parent: Command, attachOpts?: AttachOptions): Command;
|
|
143
|
+
export declare function attachDataCommand(parent: Command, attachOpts?: AttachOptions): Command;
|
|
144
|
+
export declare function attachHistoryCommand(parent: Command, attachOpts?: AttachOptions): Command;
|
|
145
|
+
export declare function attachRunInfoCommand(parent: Command, attachOpts?: AttachOptions): Command;
|
|
146
|
+
export declare function attachTriggerCommand(parent: Command, attachOpts?: AttachOptions): Command;
|
|
118
147
|
export {};
|