@trawlme/cli 1.21.0 → 1.22.0

package/dist/index.d.ts

@@ -15,6 +15,14 @@ import { Command } from 'commander';
  * chain — matching the pre-existing convention that a direct child of the
  * root (e.g. `scraps list`, `telemetry on`) is named relative to its
  * immediate group, never prefixed with the program name.
+ *
+ * #108 note: promoting a verb to a top-level command (see `createProgram`
+ * below) renamed ITS resolved telemetry name from `scraps <verb>` to
+ * `<verb>` — the canonical top-level attach and the legacy hidden
+ * `scraps <verb>` attach are two separate Command instances (scraps.ts's
+ * double-attach factories), each with its own parent chain, so they
+ * resolve to two different names here even though they run the same
+ * handler. Intentional (the canonical command IS now `<verb>`), not a bug.
  */
 export declare function resolveCommandName(actionCommand: Command | undefined): string;
 /**

package/dist/index.js

@@ -4,7 +4,7 @@ import { readFileSync, realpathSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { dirname, join } from 'node:path';
 import { login, logout } from './commands/login.js';
-import { scraps } from './commands/scraps.js';
+import { scraps, attachListCommand, attachGetCommand, attachRunCommand, attachDataCommand, attachHistoryCommand, attachRunInfoCommand, attachTriggerCommand, } from './commands/scraps.js';
 import { skills } from './commands/skills.js';
 import { telemetry } from './commands/telemetry.js';
 import { token } from './commands/token.js';
@@ -32,6 +32,14 @@ const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8
  * chain — matching the pre-existing convention that a direct child of the
  * root (e.g. `scraps list`, `telemetry on`) is named relative to its
  * immediate group, never prefixed with the program name.
+ *
+ * #108 note: promoting a verb to a top-level command (see `createProgram`
+ * below) renamed ITS resolved telemetry name from `scraps <verb>` to
+ * `<verb>` — the canonical top-level attach and the legacy hidden
+ * `scraps <verb>` attach are two separate Command instances (scraps.ts's
+ * double-attach factories), each with its own parent chain, so they
+ * resolve to two different names here even though they run the same
+ * handler. Intentional (the canonical command IS now `<verb>`), not a bug.
  */
 export function resolveCommandName(actionCommand) {
     if (!actionCommand)
@@ -63,21 +71,51 @@ export function collectCommandNames(root) {
     walk(root);
     return names;
 }
+/**
+ * #108 — surface reorg into two `trawl --help` tiers. Core verbs are
+ * agent+human, `--json` first-class, non-interactive; Management is the
+ * existing human/CI surface, kept but grouped so top-level help reads
+ * simple. Commander v14's native per-command help group (`.commandsGroup()`
+ * sets the default a subsequently-registered command inherits via
+ * `.helpGroup()`) drives the section headings — group ORDER in the printed
+ * help follows first-seen insertion order into `program.commands`, so every
+ * Core command is registered below before any Management one.
+ */
+const CORE_GROUP = 'Core commands (agent + human):';
+const MANAGEMENT_GROUP = 'Management commands (human/CI):';
 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);
+    // Core verbs (#108) — promoted/listed first: fetch, run, list, get, data,
+    // history, run-info, trigger, whoami, ping. `list`/`get`/`run`/`data`/
+    // `history`/`run-info`/`trigger` are built via scraps.ts's exported
+    // attachXCommand() factories — the SAME definition also stays wired
+    // (hidden) under `scraps` there, so every pre-#108 `trawl scraps <verb>`
+    // invocation keeps resolving (no breaking change).
+    program.commandsGroup(CORE_GROUP);
     program.addCommand(fetchUrl);
+    attachRunCommand(program);
+    attachListCommand(program);
+    attachGetCommand(program);
+    attachDataCommand(program);
+    attachHistoryCommand(program);
+    attachRunInfoCommand(program);
+    attachTriggerCommand(program);
     program.addCommand(whoami);
     program.addCommand(ping);
+    // Management (#108) — human/CI surface, grouped below. `scraps` still
+    // holds every pre-#108 management command (create/update/delete/banner/
+    // watch/account.*/session.*/doctor/autofix/snapshot) exactly as before.
+    program.commandsGroup(MANAGEMENT_GROUP);
+    program.addCommand(scraps);
+    program.addCommand(skills);
+    program.addCommand(login);
+    program.addCommand(logout);
+    program.addCommand(token);
+    program.addCommand(telemetry);
     return program;
 }
 /**

package/docs/agent-quickstart.md

@@ -0,0 +1,103 @@
+# Trawl CLI — Agent Quickstart
+
+The minimal surface an AI agent needs to drive `@trawlme/cli` non-interactively.
+For the full command reference (management surface, Claude Code skills,
+telemetry, etc.) see the [main README](../README.md) — the human/CI guide.
+
+## Auth — zero prompts
+
+Set `TRAWL_TOKEN` and every command authenticates without ever touching a
+prompt:
+
+```bash
+export TRAWL_TOKEN=<jwt>
+trawl whoami --json
+```
+
+(Interactive `trawl login` and the `--url`/config-file flow are documented in
+the README's [Authentication](../README.md#authentication) section — an
+agent should never need them.)
+
+## Core commands (agent + human)
+
+These ten commands are the CLI's agent+human surface — `--json` is
+first-class on every one, and none of them ever blocks on a prompt (see
+[Non-interactive contract](#non-interactive-contract) below):
+
+```
+trawl fetch <url> [--json] [--reason <text>]   One-shot fetch + extract readable content from a public URL (no scrap needed)
+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
+trawl data <id> [--json] [--fresh] [--errors]  Get scrap data (last persisted run, or --fresh to launch one)
+trawl history <id> [--json] [-n <limit>]       List past runs for a scrap
+trawl run-info <hid> [--json]                  Show details of a single run
+trawl trigger <id> [--watch] [--wait] [--json] Launch a scrap as a background worker
+trawl whoami [--json]                          Show the authenticated user's identity
+trawl ping [--json]                            Health/version handshake against the Trawl API
+```
+
+`trawl fetch` is the one command with no persisted scrap behind it — a
+one-shot fetch + extract for any public URL, the closest primitive to
+"just get me this page's content." It's the REST counterpart of the MCP
+`trawl_fetch_url` tool (same shared engine): `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 even though `--json` always prints the raw
+payload verbatim.
+
+> **No breaking change:** every verb above is also still reachable under its
+> pre-reorg path, `trawl scraps <verb>` (e.g. `trawl scraps list`) — kept as
+> a hidden alias. Prefer the bare top-level form above; it's what
+> `trawl --help` now shows.
+
+For the full flag reference (tier overrides on `create`/`update`, the
+`--watch` polling mechanics, retention/regression semantics on `data`, …)
+see the README's [Core commands](../README.md#core-commands-agent--human) section
+— this doc intentionally stays minimal.
+
+## `--json` contract
+
+Every command above supports `--json`: a single structured payload on
+stdout, nothing else. Two narrow exceptions carried over from the human
+surface: a `--watch` poll emits exactly one final NDJSON line once the run
+reaches a terminal state (not the whole progress stream), and there is no
+JSON form of an HTML page (irrelevant to the core verbs above — that only
+applies to the management-only `scraps snapshot`).
+
+On failure, `--json` emits a single error envelope on stdout instead of
+prose — `{"error":{"message","status?","kind"}}` — and the human-readable
+line goes to stderr, never stdout. `kind` is the machine-readable
+discriminant (`"usage"`/`"auth"`/`"not_found"`/`"network"`/`"api"`/
+`"refused"`/`"unknown"`) a script should switch on.
+
+## Non-interactive contract
+
+No core verb ever blocks waiting for a prompt. When stdin/stdout isn't a
+real TTY (any subprocess-driven invocation) — or `--json` is set — any
+command that would otherwise ask a `[y/N]` confirmation or a missing value
+instead fails fast with a structured usage error (exit `2`) rather than
+hanging. Full rule + rationale: README's
+[Non-interactive rule](../README.md#non-interactive-rule).
+
+## Exit codes
+
+| Code | Meaning |
+|------|---------|
+| `0`  | Success |
+| `1`  | Unknown/generic error, or a business-logic outcome (e.g. `fetch`'s honest `status:'failed'`/`'blocked'`, `data`'s `run_failed`/`in_progress`) |
+| `2`  | Usage error (bad flag/value, invalid ID, missing required argument, or the non-interactive guard refusing to prompt) |
+| `3`  | Auth error (not logged in, or the session token is expired/invalid) |
+| `4`  | Not found (no such resource, or no persisted payload to read) |
+| `5`  | Network error (API host unreachable, DNS/connection/TLS failure, or timeout) |
+
+This table is the stable contract; per-command nuance and overloads (e.g.
+`fetch`'s domain-level failure sharing exit `1` with an unmapped bug) are
+documented once, in the README's [Exit codes](../README.md#exit-codes)
+section — treat that as canonical if the two ever seem to disagree.
+
+## Minimal example
+
+```bash
+TRAWL_TOKEN=<jwt> trawl fetch https://example.com --json
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trawlme/cli",
-  "version": "1.21.0",
+  "version": "1.22.0",
   "description": "Trawl CLI — manage scraps from the terminal",
   "type": "module",
   "bin": {
@@ -8,6 +8,7 @@
   },
   "files": [
     "dist",
+    "docs",
     "README.md",
     "LICENSE"
   ],