@trawlme/cli 1.21.0 → 1.22.0

package/dist/commands/scraps.js

@@ -348,127 +348,133 @@ export async function pollRunProgress(id, before, opts = {}) {
     }
     process.exitCode = 1;
 }
-// list
-scraps
-    .command('list')
-    .alias('ls')
-    .description('List all scraps')
-    .option('--json', 'Output as JSON')
-    .option('--status <status>', 'Filter by last run status (success|failure|never|running|regression)')
-    // #88 item 8 — no custom parser here (unlike the old `(v) => parseInt(v,
-    // 10)`): a bad value like "abc" used to silently become NaN, which then
-    // sailed straight through `Number.isInteger`-less checks and into
-    // `.slice(0, NaN)` (silently truncates to 0 rows) or `?page=NaN` (silently
-    // sent to the server) — never a usage error. Keeping the raw string here
-    // lets the validation below mirror `history`'s own --limit check exactly
-    // (~line 660) and report the actual bad input in the error message.
-    .option('--limit <n>', 'Show only the first N results')
-    .option('--page <n>', 'Fetch a specific page only (50 per page, no auto-pagination)')
-    .action(async (opts, cmd) => {
-    // Guard: --limit and --page are mutually exclusive
-    if (opts.limit !== undefined && opts.page !== undefined) {
-        usageError('--limit and --page are mutually exclusive. Use one or the other.', { json: opts.json });
-        return;
-    }
-    let limit;
-    if (opts.limit !== undefined) {
-        limit = Number(opts.limit);
-        if (!Number.isInteger(limit) || limit <= 0) {
-            usageError(`Invalid --limit "${opts.limit}" (expected a positive integer)`, { json: opts.json });
+// list — promoted to a top-level verb (#108, see the AttachOptions comment above)
+export function attachListCommand(parent, attachOpts = {}) {
+    return parent
+        .command('list', attachOpts)
+        .alias('ls')
+        .description('List all scraps')
+        .option('--json', 'Output as JSON')
+        .option('--status <status>', 'Filter by last run status (success|failure|never|running|regression)')
+        // #88 item 8 — no custom parser here (unlike the old `(v) => parseInt(v,
+        // 10)`): a bad value like "abc" used to silently become NaN, which then
+        // sailed straight through `Number.isInteger`-less checks and into
+        // `.slice(0, NaN)` (silently truncates to 0 rows) or `?page=NaN` (silently
+        // sent to the server) — never a usage error. Keeping the raw string here
+        // lets the validation below mirror `history`'s own --limit check exactly
+        // (~line 660) and report the actual bad input in the error message.
+        .option('--limit <n>', 'Show only the first N results')
+        .option('--page <n>', 'Fetch a specific page only (50 per page, no auto-pagination)')
+        .action(async (opts, cmd) => {
+        // Guard: --limit and --page are mutually exclusive
+        if (opts.limit !== undefined && opts.page !== undefined) {
+            usageError('--limit and --page are mutually exclusive. Use one or the other.', { json: opts.json });
             return;
         }
-    }
-    let page;
-    if (opts.page !== undefined) {
-        page = Number(opts.page);
-        if (!Number.isInteger(page) || page <= 0) {
-            usageError(`Invalid --page "${opts.page}" (expected a positive integer)`, { json: opts.json });
-            return;
+        let limit;
+        if (opts.limit !== undefined) {
+            limit = Number(opts.limit);
+            if (!Number.isInteger(limit) || limit <= 0) {
+                usageError(`Invalid --limit "${opts.limit}" (expected a positive integer)`, { json: opts.json });
+                return;
+            }
         }
-    }
-    let data;
-    try {
-        data = await oraPromise(async () => {
-            if (page !== undefined) {
-                // Single-page mode: explicit page requested, no loop
-                return api.get(`/api/scraps?perPage=50&page=${page}`);
+        let page;
+        if (opts.page !== undefined) {
+            page = Number(opts.page);
+            if (!Number.isInteger(page) || page <= 0) {
+                usageError(`Invalid --page "${opts.page}" (expected a positive integer)`, { json: opts.json });
+                return;
             }
-            // Fetch-all mode: paginate until a page returns < 200 items
-            const perPage = 200;
-            let result = [];
-            let pageNum = 1;
-            while (true) {
-                const batch = await api.get(`/api/scraps?perPage=${perPage}&page=${pageNum}`);
-                result = result.concat(batch);
-                if (batch.length < perPage)
-                    break;
-                pageNum++;
+        }
+        let data;
+        try {
+            data = await oraPromise(async () => {
+                if (page !== undefined) {
+                    // Single-page mode: explicit page requested, no loop
+                    return api.get(`/api/scraps?perPage=50&page=${page}`);
+                }
+                // Fetch-all mode: paginate until a page returns < 200 items
+                const perPage = 200;
+                let result = [];
+                let pageNum = 1;
+                while (true) {
+                    const batch = await api.get(`/api/scraps?perPage=${perPage}&page=${pageNum}`);
+                    result = result.concat(batch);
+                    if (batch.length < perPage)
+                        break;
+                    pageNum++;
+                }
+                return result;
+            }, 'Fetching scraps…');
+        }
+        catch (err) {
+            // Spinner already failed by oraPromise — report with the scrap-specific
+            // prefix kept, but route through the shared classifier so exit code +
+            // --json envelope stay consistent with every other command. (#71)
+            //
+            // This bespoke catch (kept for the "Failed to fetch scraps:" prefix,
+            // which the shared reportError() can't add) used to silently swallow
+            // --debug: unlike the central index.ts catch, it never printed the raw
+            // stack trace. optsWithGlobals() reads --debug off the ROOT command
+            // (this leaf has no --debug of its own) so it can honor the flag
+            // locally instead. (#86 finding 9)
+            const isDebug = Boolean(cmd.optsWithGlobals().debug || process.env['DEBUG']);
+            const { exitCode, envelope } = classifyError(err);
+            const message = `Failed to fetch scraps: ${envelope.message}`;
+            if (isDebug)
+                console.error(err);
+            if (opts.json) {
+                console.log(JSON.stringify({ error: { ...envelope, message } }));
             }
-            return result;
-        }, 'Fetching scraps…');
-    }
-    catch (err) {
-        // Spinner already failed by oraPromise — report with the scrap-specific
-        // prefix kept, but route through the shared classifier so exit code +
-        // --json envelope stay consistent with every other command. (#71)
-        //
-        // This bespoke catch (kept for the "Failed to fetch scraps:" prefix,
-        // which the shared reportError() can't add) used to silently swallow
-        // --debug: unlike the central index.ts catch, it never printed the raw
-        // stack trace. optsWithGlobals() reads --debug off the ROOT command
-        // (this leaf has no --debug of its own) so it can honor the flag
-        // locally instead. (#86 finding 9)
-        const isDebug = Boolean(cmd.optsWithGlobals().debug || process.env['DEBUG']);
-        const { exitCode, envelope } = classifyError(err);
-        const message = `Failed to fetch scraps: ${envelope.message}`;
-        if (isDebug)
-            console.error(err);
-        if (opts.json) {
-            console.log(JSON.stringify({ error: { ...envelope, message } }));
+            else if (!isDebug) {
+                console.error(chalk.red(`✗ ${message}`));
+            }
+            process.exitCode = exitCode;
+            return;
         }
-        else if (!isDebug) {
-            console.error(chalk.red(`✗ ${message}`));
+        if (opts.status)
+            data = data.filter((s) => lastStatus(s) === opts.status);
+        const totalMatched = data.length;
+        const rows = limit !== undefined ? data.slice(0, limit) : data;
+        if (opts.json)
+            return json(rows);
+        const tableRows = rows.map((s) => ({
+            id: s._id,
+            title: s.title || '(untitled)',
+            cron: s.cron || '—',
+            status: statusIcon(lastStatus(s)),
+            'last run': lastRun(s),
+            updated: new Date(s.updatedAt).toLocaleDateString(),
+        }));
+        table(tableRows, ['id', 'title', 'cron', 'status', 'last run', 'updated']);
+        // Print footer when --limit truncates
+        if (limit !== undefined && rows.length < totalMatched) {
+            console.log(chalk.dim(`Showing ${rows.length} of ${totalMatched} — omit --limit to see all`));
         }
-        process.exitCode = exitCode;
-        return;
-    }
-    if (opts.status)
-        data = data.filter((s) => lastStatus(s) === opts.status);
-    const totalMatched = data.length;
-    const rows = limit !== undefined ? data.slice(0, limit) : data;
-    if (opts.json)
-        return json(rows);
-    const tableRows = rows.map((s) => ({
-        id: s._id,
-        title: s.title || '(untitled)',
-        cron: s.cron || '—',
-        status: statusIcon(lastStatus(s)),
-        'last run': lastRun(s),
-        updated: new Date(s.updatedAt).toLocaleDateString(),
-    }));
-    table(tableRows, ['id', 'title', 'cron', 'status', 'last run', 'updated']);
-    // Print footer when --limit truncates
-    if (limit !== undefined && rows.length < totalMatched) {
-        console.log(chalk.dim(`Showing ${rows.length} of ${totalMatched} — omit --limit to see all`));
-    }
-});
-// get
-scraps
-    .command('get <id>')
-    .description('Get scrap details')
-    .option('--json', 'Output as JSON')
-    .action(async (id, opts) => {
-    validateObjectId(id);
-    const data = await api.get(`/api/scraps/${id}`);
-    if (opts.json)
-        return json(data);
-    console.log(chalk.bold(data.title || '(untitled)'));
-    console.log(chalk.dim(`  ID:       `) + data._id);
-    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());
-});
+    });
+}
+attachListCommand(scraps, { hidden: true });
+// get — promoted to a top-level verb (#108)
+export function attachGetCommand(parent, attachOpts = {}) {
+    return parent
+        .command('get <id>', attachOpts)
+        .description('Get scrap details')
+        .option('--json', 'Output as JSON')
+        .action(async (id, opts) => {
+        validateObjectId(id);
+        const data = await api.get(`/api/scraps/${id}`);
+        if (opts.json)
+            return json(data);
+        console.log(chalk.bold(data.title || '(untitled)'));
+        console.log(chalk.dim(`  ID:       `) + data._id);
+        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());
+    });
+}
+attachGetCommand(scraps, { hidden: true });
 const VALID_TIERS = ['tier0', 'tier1', 'tier2', 'tier3', 'tier4'];
 /**
  * #86 findings 4/5 — shared honest-tier renderer for `create --tier` and
@@ -512,7 +518,7 @@ function renderTierOverrideHuman(data) {
 function warnIfUnconfirmedTier(data, tierWasRequested, id) {
     if (data._tierOverride || !tierWasRequested)
         return;
-    console.error(chalk.yellow(`  ⚠ Server did not confirm the tier change (older server) — verify with: trawl scraps get ${id}`));
+    console.error(chalk.yellow(`  ⚠ Server did not confirm the tier change (older server) — verify with: trawl get ${id}`));
 }
 /**
  * #88 item 3 — the --json machine-readable counterpart to
@@ -709,38 +715,41 @@ scraps
     if (refused)
         process.exitCode = 1;
 });
-// run
-scraps
-    .command('run <id>')
-    .description('Run a scrap')
-    .option('-w, --watch', 'Show progress after launching (polls — see `trawl scraps trigger --watch`, #91)')
-    .option('--json', 'Output the raw launch payload as JSON')
-    .action(async (id, opts) => {
-    validateObjectId(id);
-    // #91 P1 / #93 item 1 — captured BEFORE launching so pollRunProgress can
-    // tell "the run that's about to finish" apart from whatever the last run
-    // happened to be (including a dedup onto an already-in-flight run).
-    const beforeRun = opts.watch ? await captureBeforeRunState(id) : undefined;
-    // #91 P0 — GET /api/scraps/load/:id runs the scrap synchronously
-    // server-side (30-250s); the 30s default was aborting it mid-flight.
-    const call = () => api.get(`/api/scraps/load/${id}`, { timeoutMs: LONG_RUN_TIMEOUT_MS });
-    // #107 — under --json the stdout path stays pure: no spinner channel at
-    // all, mirroring `trawl fetch`'s own --json handling.
-    const data = opts.json
-        ? await call()
-        : await oraPromise(call, { text: 'Launching scrap…', successText: 'Scrap launched' });
-    if (opts.json)
-        json(data);
-    if (opts.watch) {
-        // #107 — under --json, pollRunProgress suppresses its own intermediate
-        // console.log calls and instead emits exactly ONE final NDJSON outcome
-        // line (+ sets process.exitCode honestly) once the watch reaches a
-        // terminal status, a timeout, or a persistent poll error (review F1) —
-        // `run --json --watch` never again exits 0 after dead air regardless
-        // of what the watched run actually did.
-        await pollRunProgress(id, beforeRun, { json: opts.json });
-    }
-});
+// run — promoted to a top-level verb (#108)
+export function attachRunCommand(parent, attachOpts = {}) {
+    return parent
+        .command('run <id>', attachOpts)
+        .description('Run a scrap')
+        .option('-w, --watch', 'Show progress after launching (polls — see `trawl trigger --watch`, #91)')
+        .option('--json', 'Output the raw launch payload as JSON')
+        .action(async (id, opts) => {
+        validateObjectId(id);
+        // #91 P1 / #93 item 1 — captured BEFORE launching so pollRunProgress can
+        // tell "the run that's about to finish" apart from whatever the last run
+        // happened to be (including a dedup onto an already-in-flight run).
+        const beforeRun = opts.watch ? await captureBeforeRunState(id) : undefined;
+        // #91 P0 — GET /api/scraps/load/:id runs the scrap synchronously
+        // server-side (30-250s); the 30s default was aborting it mid-flight.
+        const call = () => api.get(`/api/scraps/load/${id}`, { timeoutMs: LONG_RUN_TIMEOUT_MS });
+        // #107 — under --json the stdout path stays pure: no spinner channel at
+        // all, mirroring `trawl fetch`'s own --json handling.
+        const data = opts.json
+            ? await call()
+            : await oraPromise(call, { text: 'Launching scrap…', successText: 'Scrap launched' });
+        if (opts.json)
+            json(data);
+        if (opts.watch) {
+            // #107 — under --json, pollRunProgress suppresses its own intermediate
+            // console.log calls and instead emits exactly ONE final NDJSON outcome
+            // line (+ sets process.exitCode honestly) once the watch reaches a
+            // terminal status, a timeout, or a persistent poll error (review F1) —
+            // `run --json --watch` never again exits 0 after dead air regardless
+            // of what the watched run actually did.
+            await pollRunProgress(id, beforeRun, { json: opts.json });
+        }
+    });
+}
+attachRunCommand(scraps, { hidden: true });
 // #70 — render an items array either as a table summary or --json. Shared by
 // both the default (persisted read) and --fresh (live execute) paths of `data`.
 function renderScrapItems(items, asJson) {
@@ -774,228 +783,237 @@ function reportDataState(message, exitCode, kind, wantsJson) {
     }
     process.exitCode = exitCode;
 }
-// data
-scraps
-    .command('data <id>')
-    .description('Get scrap data (last persisted run — read-only, no quota). Use --fresh to launch a new run instead.')
-    .option('--json', 'Output as JSON')
-    .option('--errors', 'Show failure diagnostics when the last run failed')
-    .option('--fresh', 'Launch a fresh run instead of reading the last persisted payload (consumes execute quota, same as `scraps run`)')
-    .action(async (id, opts) => {
-    validateObjectId(id);
-    // --errors: fetch full run + fix detail via fetchRunAndFix (DRY with doctor).
-    // Read-only: GET /api/scraps/:id + GET /api/historys/:hid, no quota, no run lock.
-    if (opts.errors) {
-        const result = await fetchRunAndFix(id);
-        if (!result) {
-            // #88 item 7 — unified no-runs shape with `doctor --json`: a bare
-            // `null` was indistinguishable from any other absent-payload state
-            // (a scrap CAN legitimately have a null-ish result elsewhere); an
-            // explicit `{status:"no_runs"}` object is unambiguous everywhere.
-            if (opts.json) {
-                json({ status: 'no_runs' });
+// data — promoted to a top-level verb (#108)
+export function attachDataCommand(parent, attachOpts = {}) {
+    return parent
+        .command('data <id>', attachOpts)
+        .description('Get scrap data (last persisted run — read-only, no quota). Use --fresh to launch a new run instead.')
+        .option('--json', 'Output as JSON')
+        .option('--errors', 'Show failure diagnostics when the last run failed')
+        .option('--fresh', 'Launch a fresh run instead of reading the last persisted payload (consumes execute quota, same as `run`)')
+        .action(async (id, opts) => {
+        validateObjectId(id);
+        // --errors: fetch full run + fix detail via fetchRunAndFix (DRY with doctor).
+        // Read-only: GET /api/scraps/:id + GET /api/historys/:hid, no quota, no run lock.
+        if (opts.errors) {
+            const result = await fetchRunAndFix(id);
+            if (!result) {
+                // #88 item 7 — unified no-runs shape with `doctor --json`: a bare
+                // `null` was indistinguishable from any other absent-payload state
+                // (a scrap CAN legitimately have a null-ish result elsewhere); an
+                // explicit `{status:"no_runs"}` object is unambiguous everywhere.
+                if (opts.json) {
+                    json({ status: 'no_runs' });
+                    return;
+                }
+                console.log(chalk.dim('No runs yet.'));
                 return;
             }
-            console.log(chalk.dim('No runs yet.'));
+            // --json is honored for BOTH outcomes (success or failure) — an agent
+            // parsing `data --errors --json` must always get the flat run object,
+            // never prose gated behind a status check. (#71 finding 13)
+            if (opts.json)
+                return json(pickRun(result.run));
+            if (result.run.status === true) {
+                console.log(chalk.green('✓ Last run succeeded. No errors to show.'));
+                return;
+            }
+            console.log(formatDoctor(result.scrap.title, result.run, result.fix, id));
             return;
         }
-        // --json is honored for BOTH outcomes (success or failure) — an agent
-        // parsing `data --errors --json` must always get the flat run object,
-        // never prose gated behind a status check. (#71 finding 13)
-        if (opts.json)
-            return json(pickRun(result.run));
-        if (result.run.status === true) {
-            console.log(chalk.green('✓ Last run succeeded. No errors to show.'));
+        // #70 — --fresh is the explicit opt-in for a LIVE run. This is what the
+        // default path used to do silently: GET /api/scraps/load/:id executes a
+        // fresh scrap run server-side (requireQuota('scraps','execute') + a
+        // distributed run lock — trawl_node modules/scraps/routes/scraps.routes.js),
+        // burning execute quota and 429ing if a run is already in flight. A user
+        // or agent "just reading data" must never trigger that by accident.
+        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 }), {
+                text: 'Launching a fresh scrap run (consumes execute quota)…',
+                successText: 'Fresh run complete',
+            });
+            const items = loaded?.result?.data;
+            if (!Array.isArray(items)) {
+                // --json always returns an array from `data` — [] is the honest
+                // "no items" signal instead of prose breaking JSON parsing. (#71)
+                if (opts.json) {
+                    json([]);
+                    return;
+                }
+                console.log(chalk.dim('No data yet. Run the scrap first.'));
+                return;
+            }
+            // #93 item 2 — --fresh used to render items without ever checking for a
+            // regression, unlike the persisted `data` path below (#88 item 2). The
+            // load() response's OWN embedded `scrap.history[0]` can't be trusted for
+            // this (see the ScrapLoadResult comment above): it may be the previous
+            // run's row, and even the right row never carries the regression flip.
+            // `--fresh` runs synchronously to completion server-side though — by the
+            // time this call returns, node has already awaited the regression patch
+            // — so a fresh GET /api/scraps/:id (the SAME read the persisted path
+            // below already trusts) reliably observes the finalized DB state.
+            // Best-effort: never fail --fresh's real output over this side check,
+            // and never gate on it — the items returned ARE this run's real,
+            // synchronously-computed data regardless of what this check finds.
+            try {
+                const fresh = await api.get(`/api/scraps/${id}`);
+                if (fresh.history?.[0]?.statusDetail === 'regression') {
+                    console.error(chalk.yellow(`⚠ Item count regressed vs baseline for the last run of ${id} — see: trawl scraps doctor ${id}`));
+                }
+            }
+            catch {
+                // best-effort — the fresh run's items are still valid without this check
+            }
+            renderScrapItems(items, opts.json);
             return;
         }
-        console.log(formatDoctor(result.scrap.title, result.run, result.fix, id));
-        return;
-    }
-    // #70 — --fresh is the explicit opt-in for a LIVE run. This is what the
-    // default path used to do silently: GET /api/scraps/load/:id executes a
-    // fresh scrap run server-side (requireQuota('scraps','execute') + a
-    // distributed run lock — trawl_node modules/scraps/routes/scraps.routes.js),
-    // burning execute quota and 429ing if a run is already in flight. A user
-    // or agent "just reading data" must never trigger that by accident.
-    if (opts.fresh) {
-        // #91 P0 — same long-run endpoint as `scraps 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 }), {
-            text: 'Launching a fresh scrap run (consumes execute quota)…',
-            successText: 'Fresh run complete',
-        });
-        const items = loaded?.result?.data;
+        // Default: read the last PERSISTED run payload — no quota, no run lock.
+        // History.data (trawl_node modules/historys/services/historys.service.js
+        // `update()`) is a JSON-stringified clone of the worker result, so it
+        // carries the same `.data` items array the live load endpoint returns —
+        // it's just pulled from the most recent history row instead of a fresh
+        // run. Retention keeps this only for the newest row per (scrap, status)
+        // bucket (config.trawl.keepData, default 1); older rows null it out.
+        //
+        // #86 finding 6 — [] is reserved for a GENUINE zero-item successful run.
+        // Every other outcome below is an honest error envelope instead: never
+        // run (not_found/4), last run failed (1), or the payload aged out of
+        // retention (not_found/4) all used to collapse into the same silent [].
+        const scrap = await api.get(`/api/scraps/${id}`);
+        const last = scrap.history?.[0];
+        if (!last?._id) {
+            reportDataState(`Scrap ${id} has never run. Run it first (trawl run ${id}) or pass --fresh to launch one now.`, 4, 'not_found', opts.json);
+            return;
+        }
+        // #88 item 1 — status:null is an IN-FLIGHT run (node persists
+        // {status:null, statusDetail:null, inFlight:true} the moment a run
+        // starts, and only flips status/statusDetail once it finishes). That is
+        // neither "never run" nor "the last run failed" — a caller reading data
+        // mid-run needs an honest "wait" signal. Never suggest --fresh here: a
+        // run already holds the server-side distributed lock, so --fresh would
+        // just 429 against it.
+        if (last.status === null) {
+            reportDataState(`Run in progress for ${id} — retry shortly.`, 1, 'in_progress', opts.json);
+            return;
+        }
+        // #86 review — node persists status=false for a GENUINE zero-item run
+        // too (historys schema: status boolean|null + statusDetail
+        // success/error/empty/regression; a zero-item run is status=false +
+        // statusDetail='empty', and the embedded history rows from GET
+        // /api/scraps/:id include statusDetail via the repository populate
+        // select). An 'empty' run is the one case [] is FOR — only a real
+        // failure (error/unknown detail) gets the run_failed envelope.
+        //
+        // #88 item 2 — statusDetail='regression' is ALSO status=false (an async
+        // patch flips it after item count dropped vs baseline), but the row's
+        // `data` still holds REAL, non-empty items — the write that persisted
+        // them succeeded before the regression was even detected. Treating it as
+        // run_failed would hide genuine data behind a false negative.
+        const isEmptyRun = last.status === false && last.statusDetail === 'empty';
+        const isRegression = last.status === false && last.statusDetail === 'regression';
+        if (last.status === false && !isEmptyRun && !isRegression) {
+            reportDataState(`Last run failed — see: trawl data ${id} --errors`, 1, 'run_failed', opts.json);
+            return;
+        }
+        const detail = await api.get(`/api/historys/${last._id}`);
+        let items;
+        if (typeof detail?.data === 'string' && detail.data) {
+            try {
+                items = JSON.parse(detail.data)?.data;
+            }
+            catch {
+                items = undefined;
+            }
+        }
         if (!Array.isArray(items)) {
-            // --json always returns an array from `data` — [] is the honest
-            // "no items" signal instead of prose breaking JSON parsing. (#71)
-            if (opts.json) {
-                json([]);
+            if (isEmptyRun) {
+                // A genuine zero-item run whose payload is '[]' or absent — both are
+                // the SAME honest answer: no items, exit 0. Never the retention
+                // message (nothing aged out; there was nothing to persist).
+                renderScrapItems([], opts.json);
                 return;
             }
-            console.log(chalk.dim('No data yet. Run the scrap first.'));
+            // #88 item 2 — a regression row whose payload aged out of retention has
+            // nothing left to show either; fall through to the SAME honest
+            // aged-out envelope a normal successful row would get (never fabricate
+            // items, never silently succeed).
+            reportDataState(`No persisted data for the last run of ${id} — it aged out of retention. Pass --fresh to launch a new run.`, 4, 'not_found', opts.json);
             return;
         }
-        // #93 item 2 — --fresh used to render items without ever checking for a
-        // regression, unlike the persisted `data` path below (#88 item 2). The
-        // load() response's OWN embedded `scrap.history[0]` can't be trusted for
-        // this (see the ScrapLoadResult comment above): it may be the previous
-        // run's row, and even the right row never carries the regression flip.
-        // `--fresh` runs synchronously to completion server-side though — by the
-        // time this call returns, node has already awaited the regression patch
-        // — so a fresh GET /api/scraps/:id (the SAME read the persisted path
-        // below already trusts) reliably observes the finalized DB state.
-        // Best-effort: never fail --fresh's real output over this side check,
-        // and never gate on it — the items returned ARE this run's real,
-        // synchronously-computed data regardless of what this check finds.
-        try {
-            const fresh = await api.get(`/api/scraps/${id}`);
-            if (fresh.history?.[0]?.statusDetail === 'regression') {
-                console.error(chalk.yellow(`⚠ Item count regressed vs baseline for the last run of ${id} — see: trawl scraps doctor ${id}`));
-            }
-        }
-        catch {
-            // best-effort — the fresh run's items are still valid without this check
+        // #88 item 2 — a regression row's items are REAL (the write succeeded
+        // before the async patch flagged the drop) — return them on stdout
+        // (exit 0, both modes) with an honest stderr warning pointing at the
+        // diagnostic command, instead of hiding genuine data behind run_failed.
+        if (isRegression) {
+            console.error(chalk.yellow(`⚠ Item count regressed vs baseline for the last run of ${id} — see: trawl scraps doctor ${id}`));
         }
         renderScrapItems(items, opts.json);
-        return;
-    }
-    // Default: read the last PERSISTED run payload — no quota, no run lock.
-    // History.data (trawl_node modules/historys/services/historys.service.js
-    // `update()`) is a JSON-stringified clone of the worker result, so it
-    // carries the same `.data` items array the live load endpoint returns —
-    // it's just pulled from the most recent history row instead of a fresh
-    // run. Retention keeps this only for the newest row per (scrap, status)
-    // bucket (config.trawl.keepData, default 1); older rows null it out.
-    //
-    // #86 finding 6 — [] is reserved for a GENUINE zero-item successful run.
-    // Every other outcome below is an honest error envelope instead: never
-    // run (not_found/4), last run failed (1), or the payload aged out of
-    // retention (not_found/4) all used to collapse into the same silent [].
-    const scrap = await api.get(`/api/scraps/${id}`);
-    const last = scrap.history?.[0];
-    if (!last?._id) {
-        reportDataState(`Scrap ${id} has never run. Run it first (trawl scraps run ${id}) or pass --fresh to launch one now.`, 4, 'not_found', opts.json);
-        return;
-    }
-    // #88 item 1 — status:null is an IN-FLIGHT run (node persists
-    // {status:null, statusDetail:null, inFlight:true} the moment a run
-    // starts, and only flips status/statusDetail once it finishes). That is
-    // neither "never run" nor "the last run failed" — a caller reading data
-    // mid-run needs an honest "wait" signal. Never suggest --fresh here: a
-    // run already holds the server-side distributed lock, so --fresh would
-    // just 429 against it.
-    if (last.status === null) {
-        reportDataState(`Run in progress for ${id} — retry shortly.`, 1, 'in_progress', opts.json);
-        return;
-    }
-    // #86 review — node persists status=false for a GENUINE zero-item run
-    // too (historys schema: status boolean|null + statusDetail
-    // success/error/empty/regression; a zero-item run is status=false +
-    // statusDetail='empty', and the embedded history rows from GET
-    // /api/scraps/:id include statusDetail via the repository populate
-    // select). An 'empty' run is the one case [] is FOR — only a real
-    // failure (error/unknown detail) gets the run_failed envelope.
-    //
-    // #88 item 2 — statusDetail='regression' is ALSO status=false (an async
-    // patch flips it after item count dropped vs baseline), but the row's
-    // `data` still holds REAL, non-empty items — the write that persisted
-    // them succeeded before the regression was even detected. Treating it as
-    // run_failed would hide genuine data behind a false negative.
-    const isEmptyRun = last.status === false && last.statusDetail === 'empty';
-    const isRegression = last.status === false && last.statusDetail === 'regression';
-    if (last.status === false && !isEmptyRun && !isRegression) {
-        reportDataState(`Last run failed — see: trawl scraps data ${id} --errors`, 1, 'run_failed', opts.json);
-        return;
-    }
-    const detail = await api.get(`/api/historys/${last._id}`);
-    let items;
-    if (typeof detail?.data === 'string' && detail.data) {
-        try {
-            items = JSON.parse(detail.data)?.data;
+    });
+}
+attachDataCommand(scraps, { hidden: true });
+// history — list past runs for a scrap — promoted to a top-level verb (#108)
+export function attachHistoryCommand(parent, attachOpts = {}) {
+    return parent
+        .command('history <id>', attachOpts)
+        .description('List past runs for a scrap (newest first)')
+        .option('--json', 'Output as JSON')
+        .option('-n, --limit <n>', 'Max runs to show', '20')
+        .action(async (id, opts) => {
+        validateObjectId(id);
+        const limit = Number(opts.limit);
+        if (!Number.isInteger(limit) || limit < 1) {
+            usageError(`Invalid --limit "${opts.limit}" (expected a positive integer)`, { json: opts.json });
+            return;
         }
-        catch {
-            items = undefined;
+        const scrap = await api.get(`/api/scraps/${id}`);
+        const runs = (scrap.history ?? []).slice(0, limit).map((h) => ({
+            hid: h._id,
+            status: h.statusDetail ?? null,
+            time: h.time ?? null,
+            tier: h.proxyTier ?? null,
+            failureKind: h.failureKind ?? null,
+            blockType: h.blockType ?? null,
+            createdAt: h.createdAt ?? null,
+        }));
+        if (opts.json) {
+            json(runs);
+            return;
         }
-    }
-    if (!Array.isArray(items)) {
-        if (isEmptyRun) {
-            // A genuine zero-item run whose payload is '[]' or absent — both are
-            // the SAME honest answer: no items, exit 0. Never the retention
-            // message (nothing aged out; there was nothing to persist).
-            renderScrapItems([], opts.json);
+        table(runs, ['hid', 'status', 'time', 'tier', 'failureKind', 'blockType', 'createdAt']);
+    });
+}
+attachHistoryCommand(scraps, { hidden: true });
+// run-info — single-run detail by history id — promoted to a top-level verb (#108)
+export function attachRunInfoCommand(parent, attachOpts = {}) {
+    return parent
+        .command('run-info <hid>', attachOpts)
+        .description('Show details of a single run (status, tier, failureKind, error)')
+        .option('--json', 'Output as JSON')
+        .action(async (hid, opts) => {
+        validateObjectId(hid);
+        const h = await api.get(`/api/historys/${hid}`);
+        const info = {
+            hid,
+            status: h.statusDetail ?? null,
+            time: h.time ?? null,
+            tier: h.proxyTier ?? null,
+            failureKind: h.failureKind ?? null,
+            blockType: h.blockType ?? null,
+            errorMessage: h.errorSnapshot?.errorMessage ?? null,
+            selector: h.errorSnapshot?.selector ?? null,
+            emptyContext: h.errorSnapshot?.emptyContext ?? null,
+            createdAt: h.createdAt ?? null,
+        };
+        if (opts.json) {
+            json(info);
             return;
         }
-        // #88 item 2 — a regression row whose payload aged out of retention has
-        // nothing left to show either; fall through to the SAME honest
-        // aged-out envelope a normal successful row would get (never fabricate
-        // items, never silently succeed).
-        reportDataState(`No persisted data for the last run of ${id} — it aged out of retention. Pass --fresh to launch a new run.`, 4, 'not_found', opts.json);
-        return;
-    }
-    // #88 item 2 — a regression row's items are REAL (the write succeeded
-    // before the async patch flagged the drop) — return them on stdout
-    // (exit 0, both modes) with an honest stderr warning pointing at the
-    // diagnostic command, instead of hiding genuine data behind run_failed.
-    if (isRegression) {
-        console.error(chalk.yellow(`⚠ Item count regressed vs baseline for the last run of ${id} — see: trawl scraps doctor ${id}`));
-    }
-    renderScrapItems(items, opts.json);
-});
-// history — list past runs for a scrap
-scraps
-    .command('history <id>')
-    .description('List past runs for a scrap (newest first)')
-    .option('--json', 'Output as JSON')
-    .option('-n, --limit <n>', 'Max runs to show', '20')
-    .action(async (id, opts) => {
-    validateObjectId(id);
-    const limit = Number(opts.limit);
-    if (!Number.isInteger(limit) || limit < 1) {
-        usageError(`Invalid --limit "${opts.limit}" (expected a positive integer)`, { json: opts.json });
-        return;
-    }
-    const scrap = await api.get(`/api/scraps/${id}`);
-    const runs = (scrap.history ?? []).slice(0, limit).map((h) => ({
-        hid: h._id,
-        status: h.statusDetail ?? null,
-        time: h.time ?? null,
-        tier: h.proxyTier ?? null,
-        failureKind: h.failureKind ?? null,
-        blockType: h.blockType ?? null,
-        createdAt: h.createdAt ?? null,
-    }));
-    if (opts.json) {
-        json(runs);
-        return;
-    }
-    table(runs, ['hid', 'status', 'time', 'tier', 'failureKind', 'blockType', 'createdAt']);
-});
-// run-info — single-run detail by history id
-scraps
-    .command('run-info <hid>')
-    .description('Show details of a single run (status, tier, failureKind, error)')
-    .option('--json', 'Output as JSON')
-    .action(async (hid, opts) => {
-    validateObjectId(hid);
-    const h = await api.get(`/api/historys/${hid}`);
-    const info = {
-        hid,
-        status: h.statusDetail ?? null,
-        time: h.time ?? null,
-        tier: h.proxyTier ?? null,
-        failureKind: h.failureKind ?? null,
-        blockType: h.blockType ?? null,
-        errorMessage: h.errorSnapshot?.errorMessage ?? null,
-        selector: h.errorSnapshot?.selector ?? null,
-        emptyContext: h.errorSnapshot?.emptyContext ?? null,
-        createdAt: h.createdAt ?? null,
-    };
-    if (opts.json) {
-        json(info);
-        return;
-    }
-    table([info], ['hid', 'status', 'time', 'tier', 'failureKind', 'blockType', 'errorMessage', 'selector', 'emptyContext', 'createdAt']);
-});
+        table([info], ['hid', 'status', 'time', 'tier', 'failureKind', 'blockType', 'errorMessage', 'selector', 'emptyContext', 'createdAt']);
+    });
+}
+attachRunInfoCommand(scraps, { hidden: true });
 // delete
 scraps
     .command('delete <id>')
@@ -1088,46 +1106,49 @@ scraps
     validateObjectId(id);
     await watchActivities(id, opts.json);
 });
-// trigger
-scraps
-    .command('trigger <id>')
-    .description('Launch a scrap as a background worker (returns immediately)')
-    .option('-w, --watch', 'Poll for progress after triggering (#91 — the default async run happens in a separate cron pod; activities SSE never reaches it)')
-    .option('--wait', 'Run synchronously and wait for the result (legacy behaviour)')
-    .option('--json', 'Output the raw trigger payload as JSON')
-    .action(async (id, opts) => {
-    validateObjectId(id);
-    // #91 P1 / #93 item 1 — captured BEFORE triggering so pollRunProgress can
-    // tell "the run we just triggered" apart from whatever the last run
-    // happened to be. This is the dedup-prone path: `trigger`'s method:'worker'
-    // collapses onto an already-pending/running worker job for the same scrap
-    // (ScrapJobsService, LIVE_STATUSES) instead of creating a new history row —
-    // captureBeforeRunState records that so pollRunProgress can still track it.
-    const beforeRun = opts.watch ? await captureBeforeRunState(id) : undefined;
-    // #50 — default async: the backend (#1313) kicks off the run and returns a
-    // 'queued' envelope immediately instead of holding the connection for the
-    // whole run. --wait restores the old synchronous round-trip.
-    const path = opts.wait ? `/api/scraps/worker/${id}` : `/api/scraps/worker/${id}?wait=false`;
-    // #91 P0 — the synchronous --wait branch runs the scrap server-side
-    // (30-250s), same as `scraps run`; the 30s default was aborting it
-    // mid-flight. The async (default) POST returns almost immediately, so it
-    // keeps the 30s default.
-    const call = () => (opts.wait ? api.post(path, undefined, { timeoutMs: LONG_RUN_TIMEOUT_MS }) : api.post(path));
-    // #107 — under --json the stdout path stays pure: no spinner channel.
-    const data = opts.json
-        ? await call()
-        : await oraPromise(call, {
-            text: opts.wait ? 'Running worker…' : 'Triggering worker…',
-            successText: opts.wait ? 'Worker run complete' : 'Worker triggered',
-        });
-    if (opts.json)
-        json(data);
-    // #107 — see the matching comment on `run`'s --watch call above (review
-    // F1): honest final NDJSON line + exit code under --json, human mode
-    // gets the same honest exit code too.
-    if (opts.watch)
-        await pollRunProgress(id, beforeRun, { json: opts.json });
-});
+// trigger — promoted to a top-level verb (#108)
+export function attachTriggerCommand(parent, attachOpts = {}) {
+    return parent
+        .command('trigger <id>', attachOpts)
+        .description('Launch a scrap as a background worker (returns immediately)')
+        .option('-w, --watch', 'Poll for progress after triggering (#91 — the default async run happens in a separate cron pod; activities SSE never reaches it)')
+        .option('--wait', 'Run synchronously and wait for the result (legacy behaviour)')
+        .option('--json', 'Output the raw trigger payload as JSON')
+        .action(async (id, opts) => {
+        validateObjectId(id);
+        // #91 P1 / #93 item 1 — captured BEFORE triggering so pollRunProgress can
+        // tell "the run we just triggered" apart from whatever the last run
+        // happened to be. This is the dedup-prone path: `trigger`'s method:'worker'
+        // collapses onto an already-pending/running worker job for the same scrap
+        // (ScrapJobsService, LIVE_STATUSES) instead of creating a new history row —
+        // captureBeforeRunState records that so pollRunProgress can still track it.
+        const beforeRun = opts.watch ? await captureBeforeRunState(id) : undefined;
+        // #50 — default async: the backend (#1313) kicks off the run and returns a
+        // 'queued' envelope immediately instead of holding the connection for the
+        // whole run. --wait restores the old synchronous round-trip.
+        const path = opts.wait ? `/api/scraps/worker/${id}` : `/api/scraps/worker/${id}?wait=false`;
+        // #91 P0 — the synchronous --wait branch runs the scrap server-side
+        // (30-250s), same as `run`; the 30s default was aborting it
+        // mid-flight. The async (default) POST returns almost immediately, so it
+        // keeps the 30s default.
+        const call = () => (opts.wait ? api.post(path, undefined, { timeoutMs: LONG_RUN_TIMEOUT_MS }) : api.post(path));
+        // #107 — under --json the stdout path stays pure: no spinner channel.
+        const data = opts.json
+            ? await call()
+            : await oraPromise(call, {
+                text: opts.wait ? 'Running worker…' : 'Triggering worker…',
+                successText: opts.wait ? 'Worker run complete' : 'Worker triggered',
+            });
+        if (opts.json)
+            json(data);
+        // #107 — see the matching comment on `run`'s --watch call above (review
+        // F1): honest final NDJSON line + exit code under --json, human mode
+        // gets the same honest exit code too.
+        if (opts.watch)
+            await pollRunProgress(id, beforeRun, { json: opts.json });
+    });
+}
+attachTriggerCommand(scraps, { hidden: true });
 // account subcommand group
 const account = scraps
     .command('account')