@trawlme/cli 3.11.0 → 3.12.1

package/dist/commands/login.js

@@ -28,60 +28,11 @@ async function promptEmail() {
         rl.close();
     }
 }
-/** #107 — the shared success-reporting tail for all three login paths (env
- * token, --token flag, email/password). Under --json, prints a single
- * structured result on stdout instead of the chalk lines — never the raw
- * token itself (that's what `trawl token` is for). */
 function reportLoginSuccess(opts, email) {
-    // #169 review finding 3 — stderr, both under --json and plain output: this
-    // is a warning about what happens AFTER login succeeds, not part of either
-    // payload shape, so it must never be silently dropped just because --json
-    // is set.
     const overrideVar = getLiveAuthEnvVar();
     if (overrideVar) {
         console.error(chalk.yellow(`⚠ ${overrideVar} is set in your environment — it overrides the token just stored here for every subsequent command until you unset it.`));
     }
-    // #184 — `login` is the ONE intentional human setup moment: bootstrap any
-    // bundled Claude skill the user doesn't have yet. Gated exactly like
-    // every other filesystem-mutating side effect in this CLI
-    // (json/TTY/opt-out — see lib/skills.ts's isSkillsActionAllowed), so a
-    // CI/agent `TRAWL_TOKEN=x trawl login --json` never writes into
-    // ~/.claude/skills on a machine with no Claude Code session to discover
-    // them. `isInteractive` is the exact TTY definition login already uses
-    // for its own email/password prompt gate (lib/confirm.ts) — stdin AND
-    // stdout, not just stdout. `bootstrapped` is `null` ONLY when gated out
-    // (json/non-TTY/opted-out) or when every bundled skill is already owned
-    // by trawl — the genuine "nothing to do" case, where the lines below
-    // naturally never print. It is non-null whenever anything was attempted,
-    // whether or not any of it actually landed — see the block below.
-    //
-    // stderr, same convention as the `overrideVar` warning right above (and
-    // for the same reason): this is orthogonal to the `--json` envelope's
-    // fixed shape below, so it must never risk landing on stdout — a defense
-    // that holds even if `bootstrapSkillsOnLogin`'s own json/TTY gate above it
-    // were ever wrong, not just a style match.
-    //
-    // #184 review (BLOCK + MAJOR) — `bootstrapped` is non-null whenever there
-    // was anything to attempt, whether or not any of it actually landed, so
-    // both halves below must be checked independently: `installed` prints the
-    // success line, `skipped` prints one honest line per skill that was
-    // requested but did NOT land (a permission error, or a pre-existing
-    // marker-less dir the ownership guard refused to overwrite) and WHY —
-    // `reason` is already a relayable, fact-only string (SkillOwnershipRefusalError's
-    // `.relayableReason`, or a raw fs error message) with no imperative, so it
-    // is safe to print verbatim on this channel. A total failure (installed
-    // empty, skipped non-empty) must read as "attempted and failed" — never
-    // fall through to silence, which is indistinguishable from "never
-    // attempted" (the exact false-success shape this issue exists to
-    // prevent). The restart note only applies to what actually landed, so it
-    // stays scoped to that branch.
-    //
-    // #184 defect 2 — `error` is the THIRD case: distinct from both "nothing
-    // to do" (bootstrapped is `null`, nothing prints) and "some/all skills
-    // failed" (`skipped`, above) — it means bootstrapSkillsOnLogin could not
-    // even determine which skills to install (the bundled skills package
-    // looks missing/corrupted). Stated as a fact, same convention as every
-    // other line here.
     const bootstrapped = bootstrapSkillsOnLogin({ json: opts.json, isTTY: isInteractive(opts) });
     if (bootstrapped) {
         if (bootstrapped.error) {
@@ -113,17 +64,11 @@ export const login = new Command('login')
     .option('-p, --password <password>', 'Password (CI only — visible in process list and shell history)')
     .option('--json', 'Output as JSON')
     .action(async (opts) => {
-    // Validate --url but do NOT persist it yet. A failed signin must not
-    // brick the config by pointing it at an unreachable/wrong host while the
-    // OLD token stays stored (and would then be sent to that new host on the
-    // next command). Target this run via `pendingUrl` and persist only once
-    // a token has actually been obtained. (#68)
     const pendingUrl = opts.url ? requireUrl(opts.url, '--url') : undefined;
     const persistUrlIfPending = () => {
         if (pendingUrl)
             config.set('apiUrl', pendingUrl);
     };
-    // Check environment variable override first
     const envToken = process.env['TRAWL_TOKEN'];
     if (envToken) {
         config.set('token', requireFreshJwt(envToken, 'TRAWL_TOKEN'));
@@ -131,20 +76,15 @@ export const login = new Command('login')
         reportLoginSuccess(opts);
         return;
     }
-    // --token flag: direct JWT (CI / retrocompat)
     if (opts.token) {
         config.set('token', requireFreshJwt(opts.token, '--token'));
         persistUrlIfPending();
         reportLoginSuccess(opts);
         return;
     }
-    // Email/password flow
     if (opts.password) {
         console.error(chalk.yellow('Warning: passing --password on the command line is insecure.'));
     }
-    // #107 — never blocks on a readline prompt under --json or a non-TTY
-    // invocation (agent/CI subprocess); refuses with a clear, structured
-    // usage error instead, naming the flag (or TRAWL_TOKEN) to pass.
     if (!opts.email) {
         requireInteractive('Email is required — pass -e/--email, --token, or set TRAWL_TOKEN (refusing to block on a prompt, non-interactive).', { json: opts.json });
     }
@@ -154,7 +94,6 @@ export const login = new Command('login')
     const email = opts.email ?? (await promptEmail());
     const password = opts.password ?? (await promptPassword('Password: '));
     const { data, headers } = await api.publicPost('/api/auth/signin', { email, password }, pendingUrl);
-    // 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') ?? '';
@@ -175,12 +114,6 @@ export const logout = new Command('logout')
     .option('--json', 'Output as JSON')
     .action((opts) => {
     config.set('token', '');
-    // #169 review finding 3 — this is the sharpest version of the gap: an
-    // operator runs `logout` SPECIFICALLY to kill access, and if
-    // TRAWL_API_KEY/TRAWL_TOKEN is set, access is NOT killed — every
-    // subsequent command keeps authenticating with the env credential this
-    // command cannot touch. The wording below must not read as a variant of
-    // "logged out"; it says plainly that access is still live.
     const overrideVar = getLiveAuthEnvVar();
     if (overrideVar) {
         console.error(chalk.yellow(`⚠ ${overrideVar} is still set in your environment — access is NOT revoked. Every subsequent command will keep authenticating with it until you unset it (or revoke the key in the dashboard).`));

package/dist/commands/ping.d.ts

@@ -1,19 +1,4 @@
 import { Command } from 'commander';
-/**
- * `GET /api/health` response shape (home.controller.js#health,
- * home.service.js#getHealthStatus) — MCP `trawl_health_ping` parity
- * (`{ok, version, uptime}`). The REST route enriches the payload with
- * `version`/`uptime`/`db`/`memory` ONLY for an admin caller
- * (home.controller.js's `isAdmin` gate); a non-admin JWT gets `{status:'ok'}`
- * alone on a healthy server. A non-2xx response (degraded, `status:503`)
- * throws an ApiError like any other failed request — but a 2xx response is
- * NOT a guarantee that `status === 'ok'` (#106 review F5): a soft-degraded
- * signal (e.g. a partial dependency outage) could still come back as a 200
- * with a non-"ok" `status`. The HTTP call not throwing only means the
- * transport succeeded, never that the reported health is good — so the
- * human-mode `✓ OK` line is gated on the actual field, not assumed from a
- * successful round-trip.
- */
 export interface PingResponse {
     status: string;
     db?: string;

package/dist/commands/ping.js

@@ -6,33 +6,18 @@ export const ping = new Command('ping')
     .description('Health/version handshake against the Trawl API')
     .option('--json', 'Output as JSON')
     .action(async (opts) => {
-    // #148 — the server route is optionalAuth (public, enriched for an admin
-    // JWT — see the PingResponse doc above); `api.publicGet` mirrors that:
-    // it attaches a stored/env token when one happens to be available but
-    // never REQUIRES one, so `ping` works as a zero-config sanity check even
-    // with no `trawl login` ever run. `api.get` (the authenticated path)
-    // would throw notLoggedInError() locally before this ever reached the
-    // network, defeating the whole point of a pre-login handshake.
     const data = await api.publicGet('/api/health');
-    // #106 review (kimi) — honest exit code: a soft-degraded 200 (status !== 'ok')
-    // must exit non-zero so `trawl ping || handle_degraded` doesn't treat a
-    // degraded API as healthy. Applies in BOTH --json and human modes, alongside
-    // the raw/decorated output below.
     if (data.status !== 'ok')
         process.exitCode = 1;
     if (opts.json) {
         json(data);
         return;
     }
-    // #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);
     }
     else {
-        // #106 review F5 — never green-light a degraded API just because the
-        // HTTP call didn't throw; show the real reported status instead.
         console.log(chalk.yellow(`⚠ ${data.status}`) + versionSuffix);
     }
 });

package/dist/commands/scraps.d.ts

@@ -1,138 +1,18 @@
 import { Command } from 'commander';
-/**
- * #108 — surface reorg. `run`/`list`/`get`/`data`/`history`/`run-info`/
- * `trigger` are promoted to top-level verbs (see index.ts's `createProgram`)
- * alongside `create`/`whoami`/`ping` (#114 — `create` replaced `fetch` in
- * that group). Each is built by an exported
- * `attachXCommand(parent, attachOpts)` factory instead of a fixed
- * `scraps.command(...)` chain, so it can be attached TWICE with a single
- * source-of-truth definition: once to `program` (the new canonical
- * top-level path) and once more, hidden, right back onto `scraps` — so every
- * pre-#108 `trawl scraps <verb>` invocation keeps resolving unchanged
- * (`{ hidden: true }` only affects help visibility, never resolution).
- *
- * Future-drift guard: ALL `.option()`/`.argument()`/`.action()` wiring for a
- * promoted verb MUST live INSIDE its `attachXCommand` factory body, never
- * bolted onto one of its two call sites (index.ts's `createProgram` for the
- * top-level attach, this file's own `attachXCommand(scraps, { hidden: true
- * })` call for the legacy one). That's the only thing keeping `trawl run
- * <id>` and `trawl scraps run <id>` identical — a call-site-only tweak to
- * one attachment would silently diverge the two.
- */
 type AttachOptions = {
     hidden?: boolean;
 };
 export declare const scraps: Command;
-/** The top-of-history snapshot pollRunProgress needs to identify which run
- * it's watching — see captureBeforeRunState.
- *
- * #97 — `captured` discriminates WHY `id` is undefined: `true` means the GET
- * succeeded and the scrap genuinely has no history yet (an honest "never
- * run" signal pollRunProgress can trust immediately); `false` means the GET
- * itself threw, so `id`/`alreadyInFlight` carry NO information at all — the
- * scrap could easily have prior (possibly terminal) history that this
- * lookup simply never saw. Before this field existed, both cases produced
- * the identical `{id: undefined, alreadyInFlight: false}` shape, so
- * pollRunProgress could not tell them apart (see its own #97 comment).
- */
 interface BeforeRunState {
     id?: string;
     alreadyInFlight: boolean;
     captured: boolean;
 }
-/** The machine-readable outcome `pollRunProgress` prints as the single final
- * NDJSON line under `--json` (#107 review F1). `status` is the same honest
- * terminal string the human-mode "Run finished: <status>" line already
- * shows (`success`/`error`/`empty`/`regression`/…), or `'timeout'` /
- * `'poll_error'` for the two non-terminal exits. */
 export interface PollOutcome {
     runId?: string;
     status: string;
-    /** Present only for `status:'poll_error'` — the last poll failure's message. */
     error?: string;
 }
-/**
- * #91 P1 — replaces "await the run to completion, THEN open the activities
- * SSE stream" (which showed NOTHING: the activities SSE
- * (GET /api/scraps/:id/activities/stream) is backed by an in-process
- * EventEmitter with no backlog — trawl_node
- * modules/activities/services/activities.service.js — so by the time a
- * synchronous run has already finished there is nothing left to emit; and
- * the async `trigger` default enqueues the run onto a durable job queue a
- * SEPARATE cron-consumer pod drains, whose in-process emitter never reaches
- * the API pod holding the SSE connection at all).
- *
- * Instead this polls two REST reads that are BOTH Mongo-backed (not
- * in-process), so they work no matter which pod actually executed the run:
- *  - GET /api/scraps/:id/activities?history=<hid>&limit=20 — the SAME
- *    activities-list endpoint `doctor`'s fetchRunAndFix already calls
- *    (src/commands/doctor.ts) — prints each new activity line once the new
- *    run's history id is known.
- *  - GET /api/scraps/:id — history[0].status/statusDetail, the SAME
- *    terminal-status signal `lastStatus()` above already trusts (status:null
- *    === in flight, #88 item 1) to know when the run is done.
- *
- * #93 item 1 — dedup-race fix. "Is this the run we're watching?" used to be
- * a single check: `history[0]._id !== beforeHistoryId`. That's wrong when
- * `before.alreadyInFlight` is true (a `trigger` call deduped onto a worker
- * job that was ALREADY pending/running at capture time): the top row IS the
- * run we're watching, but its `_id` never changes, so the old guard never
- * released and the poll ran the full timeout to a false "Timed out". The run
- * we're watching is now EITHER a brand-new id (fresh trigger, the common
- * case) OR the same id that was already in-flight (status:null) at capture
- * (the dedup case) — a same-id row that was already TERMINAL at capture is
- * neither, and must not be latched onto as "done" (it's just the previous
- * run, still sitting there until a genuinely new run supersedes it).
- *
- * #97 — capture-failed fallback. The dedup-race fix above assumes `before`
- * is trustworthy. When `captureBeforeRunState`'s own GET threw,
- * `before.id` is `undefined` — and that is INDISTINGUISHABLE from "the
- * scrap has genuinely never run" (also `id: undefined`), which is exactly
- * the case `isNewRun` above is designed to match on the very first row that
- * ever appears. So on the very first poll, ANY pre-existing history row —
- * even the STALE PREVIOUS run, already terminal — satisfied
- * `last._id !== undefined` and got reported as "the run we just launched"
- * finishing, when it was really just whatever ran before.
- *
- * Fix: `before.captured === false` defers trusting a baseline at all.
- * Instead of comparing against the (unknown) `beforeId` from the start, the
- * FIRST successful poll read is treated as the deferred capture itself —
- * exactly what `captureBeforeRunState` would have returned had its GET
- * succeeded — and only READS from that point on are compared against it,
- * via the exact same `isNewRun` / `isDedupOntoInFlight` logic above. A
- * pre-existing terminal row observed on that first read becomes `beforeId`
- * (not a match for itself), so it correctly falls into "still the stale
- * previous run" below and the poll keeps waiting; a row still in flight
- * becomes the `alreadyInFlight` baseline, exactly like a successful capture
- * would have recorded. Either way this costs at most one extra poll
- * interval, bounded by the same deadline as everything else. The one
- * remaining edge case — capture failed AND the scrap never ran before AND
- * the triggered run already finished by the very first poll — is genuinely
- * undecidable from "stale pre-existing row" with no more information than
- * this function has, so it resolves to the same honest timeout rather than
- * risk reporting a possibly-wrong outcome (never a lie, at worst a timeout
- * telling the caller to check `doctor`).
- *
- * #107 review F1 — before this fix, `run|trigger --json --watch` was
- * outcome-blind: `quiet` suppressed ALL output (including "Run finished:
- * failure" and the timeout notice), a transient poll error was caught and
- * silently retried FOREVER within the deadline, and the process always
- * exited 0 after the poll loop regardless of what the watched run actually
- * did — dead air, then a clean exit code, even for a failed or timed-out
- * run. An agent scripting this CLI had no way to tell success from failure
- * from "we gave up". Fixed by:
- *  - emitting exactly ONE final NDJSON line on stdout under `--json` once
- *    the watch reaches ANY of its three exits (terminal status, timeout, or
- *    a persistent poll error) — `{runId,status}` (+`error` for a poll
- *    error) — while every intermediate progress line stays suppressed
- *    (unchanged from before);
- *  - setting `process.exitCode` non-zero on a genuine run failure, a
- *    timeout, or a persistent poll error, and `0` on a real success — in
- *    BOTH `--json` and human `--watch` modes (human mode used to exit 0
- *    unconditionally, the same bug, just silent instead of dishonest);
- *  - giving up after `MAX_CONSECUTIVE_POLL_ERRORS` consecutive failed reads
- *    instead of retrying the same dead endpoint for the full 300s.
- */
 export declare function pollRunProgress(id: string, before: BeforeRunState | undefined, opts?: {
     intervalMs?: number;
     timeoutMs?: number;