@hunt-labs/bytekit-cli 0.5.0 → 0.7.0

package/dist/commands/screenshots.js

@@ -2,7 +2,7 @@ import { Command, InvalidArgumentError } from 'commander';
 import { buildClient } from '../client.js';
 import { printResult, handleError } from '../output.js';
 import { downloadArtifact } from '../lib/download-artifact.js';
-import { parseEnum, parseIntFlag } from '../lib/parse-flags.js';
+import { parseEnum, parseIntFlag, parseJsonFlag } from '../lib/parse-flags.js';
 /** `ScreenshotRequest` spec enums. */
 const DEVICES = ['desktop', 'mobile'];
 const FORMATS = ['jpeg', 'png'];
@@ -23,12 +23,122 @@ export function parseClip(value) {
         throw new InvalidArgumentError('--clip must be X,Y,WIDTH,HEIGHT (e.g. 0,0,800,600).');
     return { x: Number(m[1]), y: Number(m[2]), width: Number(m[3]), height: Number(m[4]) };
 }
+/**
+ * Exit code when a queued (202 async) envelope reaches human output (#2596).
+ *
+ * Mirrors `scrape create`'s own `QUEUED_EXIT_CODE` (`commands/scrape.ts:40`) EXACTLY, and is
+ * likewise a LOCAL constant rather than an import — the two commands agree on the value, not on a
+ * shared symbol, and the guard stays where the ticket pins it (the screenshots async branch)
+ * instead of migrating into the shared printer, where it would silently set exit 2 for every
+ * command that prints a result.
+ *
+ * Deliberately NOT 0 (a completed capture) and NOT 1 (a usage/API error): the job WAS accepted and
+ * billed, the artifact simply does not exist yet, and a distinct code lets a caller branch on
+ * "queued" without parsing stderr.
+ *
+ * BREAKING (#2596): `screenshots create --async` previously exited 0. See the README exit-code
+ * table and the CHANGELOG `[0.6.0]` note (`[Unreleased]` is kept deliberately empty per
+ * `packaging.test.ts:203`; see #2620).
+ *
+ * Also carried by a NOT-READY `screenshots get -o` poll (#2686 item 1) — same meaning, same value:
+ * accepted and billed, artifact not materialized yet.
+ */
+const QUEUED_EXIT_CODE = 2;
+/**
+ * The ONLY statuses a screenshot can still reach `completed` from, and therefore the only ones
+ * worth telling a caller to poll (#2792). Every other value of `status` — the terminal ones, and
+ * anything the server may add later — is a state polling cannot improve.
+ */
+const POLLABLE_STATUSES = ['pending', 'processing'];
+/**
+ * A still-pollable screenshot poll that can hand its `ss_` handle back, or undefined.
+ *
+ * "Not ready" is `status === 'pending' || status === 'processing'` and nothing else, plus a usable
+ * `ss_` handle and no materialized `image_url` (#2792). Before that gate existed the predicate
+ * decided from `error`/`image_url`/`id` alone and read `status` only to LABEL the message, so a
+ * `completed` envelope with a null `image_url`, a status outside the enum, and the FLAT
+ * `error_code`/`error_message` failed shape that `serializeScreenshot` emits all received "poll
+ * again" advice for a job that would never complete — the exact loop the exclusion exists to
+ * prevent.
+ *
+ * Two shapes are excluded deliberately rather than incidentally:
+ *
+ * - **No `status` at all (#2792 E1).** Not treated as pending. `serializeScreenshot`
+ *   (`gateway/src/routes/screenshots.ts:365`) always writes `status`, so a statusless envelope is
+ *   not something the server produces; and an envelope carrying no evidence that work is in
+ *   progress is exactly what must not be advertised as pollable. It takes the error path, which
+ *   names the state instead of promising an artifact.
+ * - **A status outside the enum (#2792 E3).** Same reasoning, stated as the closed-set gate: a new
+ *   server status is unknown to this build, so it is reported, never polled and never fallen
+ *   through into the download path.
+ *
+ * And one shape is deliberately NOT excluded: a pollable status carrying a flat `error_code`. That
+ * is the ordinary RETRY envelope, not a verdict — see {@link flatScreenshotFailure}. Excluding it
+ * would abandon a job the server is actively retrying (#2792 B1).
+ *
+ * An envelope with no string `id` is excluded too — there is no handle to emit, so the ordinary
+ * error path (which at least names the status) is the honest outcome.
+ */
+function notReadyScreenshot(result) {
+    if (typeof result !== 'object' || result === null)
+        return undefined;
+    const obj = result;
+    // The gate, not merely the label: `status` decides, and the closed list is the whole decision.
+    const status = POLLABLE_STATUSES.find((s) => s === obj.status);
+    if (status === undefined)
+        return undefined;
+    // The NESTED error envelope stays disqualifying, exactly as before this ticket. A flat
+    // `error_code` is NOT consulted here: on a pollable status it is a retry error (#2792 B1), and
+    // the nested shape can never co-occur with a pollable status to disagree — it is built only by
+    // `buildFailedScreenshotEnvelope`, under `status === 'failed'` (`routes/screenshots.ts:267`).
+    if (obj.error !== undefined && obj.error !== null)
+        return undefined;
+    if (typeof obj.image_url === 'string' && obj.image_url.length > 0)
+        return undefined;
+    if (typeof obj.id !== 'string' || obj.id.length === 0)
+        return undefined;
+    return { id: obj.id, status };
+}
+/**
+ * The failure carried by the FLAT `error_code`/`error_message` fields, or undefined (#2792).
+ *
+ * `serializeScreenshot` (gateway `routes/screenshots.ts:365`) — and therefore the spec's own
+ * `ScreenshotResponse` — reports a failure as top-level `error_code`/`error_message`, while
+ * `buildFailedScreenshotEnvelope` (`:295`, #2027) reports it NESTED as `{error:{code,message}}`.
+ * Only the nested one was ever read, so a flat failure surfaced neither code nor message.
+ *
+ * These two are NOT interchangeable, which is why this helper reads only one of them:
+ *
+ * - The nested envelope is built only under `status === 'failed'` (`routes/screenshots.ts:267`), so
+ *   it is always terminal.
+ * - The flat columns are ALSO written by the non-terminal retry path — `job-queue.ts:346-356` sets
+ *   `error_code`/`error_message` and `status = 'pending'` in one UPDATE, and `claim()` (`:276-284`)
+ *   carries them into the next `processing` attempt. On a pollable status they describe the attempt
+ *   that just failed, not the job's outcome (#2792 B1).
+ *
+ * So the caller consults this only once the status is no longer pollable.
+ */
+function flatScreenshotFailure(obj) {
+    const detail = {};
+    if (typeof obj.error_code === 'string' && obj.error_code.length > 0)
+        detail.code = obj.error_code;
+    if (typeof obj.error_message === 'string' && obj.error_message.length > 0)
+        detail.message = obj.error_message;
+    return detail.code === undefined && detail.message === undefined ? undefined : detail;
+}
 /**
  * Extract a non-empty string `image_url` from a screenshot envelope, or throw an actionable error.
  *
- * A pending/processing envelope has no `image_url` yet; a terminal-`failed` screenshot returns the
- * unified `Error` envelope on a 200 (#2027). Either way the artifact was never materialized, so we
- * throw rather than fetching `undefined` (#2480 E5).
+ * A pending/processing envelope has no `image_url` yet; a terminal-`failed` screenshot reports its
+ * failure either nested or flat. Either way the artifact was never materialized, so we throw rather
+ * than fetching `undefined` (#2480 E5).
+ *
+ * The NESTED shape's message is untouched by #2792 — the ticket's Specification pins it as an
+ * inverse case ("the nested-error failed shape keeps its current exit-1 message"), and it is now
+ * pinned by an exact-equality test rather than the substring assertions that would not have
+ * noticed. The FLAT shape, which previously reported nothing at all, names both of its fields as
+ * `<message> (<code>)` — `extractRawBody`'s format for a failed scrape, so the two poll commands
+ * read alike — degrading to whichever field exists.
  */
 function extractImageUrl(result) {
     if (typeof result === 'object' && result !== null) {
@@ -40,8 +150,28 @@ function extractImageUrl(result) {
             return obj.image_url;
         }
         const status = typeof obj.status === 'string' ? obj.status : 'unknown';
-        throw new Error(`not ready yet: screenshot is ${status}`);
+        // "not ready yet" is reserved for a genuinely pollable state (#2792). It is still reachable
+        // here for a pending/processing envelope carrying no `ss_` id — `notReadyScreenshot` rejects
+        // those for want of a handle, and this message stays their wording. Reached BEFORE the flat
+        // failure below, because on a pollable status those columns describe the attempt that just
+        // failed and is being retried, not the job's outcome (#2792 B1).
+        if (POLLABLE_STATUSES.includes(status)) {
+            throw new Error(`not ready yet: screenshot is ${status}`);
+        }
+        const flat = flatScreenshotFailure(obj);
+        if (flat !== undefined) {
+            const reason = flat.message !== undefined && flat.code !== undefined
+                ? `${flat.message} (${flat.code})`
+                : (flat.message ?? flat.code ?? 'unknown error');
+            throw new Error(`screenshot failed: ${reason}`);
+        }
+        // Every other artifact-less state says so rather than implying the artifact soon will exist: a
+        // `completed` row with a null `image_url`, and any status this build does not know.
+        throw new Error(`no image artifact available: screenshot is ${status}`);
     }
+    // The non-object arm keeps its original wording, pinned by #2480 cr-5
+    // (`screenshot-download.test.ts:287`): this is not a screenshot envelope at all, so neither the
+    // status gate above nor its vocabulary applies.
     throw new Error('not ready yet: screenshot is unknown');
 }
 /**
@@ -53,9 +183,43 @@ function extractImageUrl(result) {
 async function emitScreenshot(result, opts) {
     if (opts.isAsync === true) {
         printResult(result, opts.json);
+        // Discriminate on the --async FLAG, never on the response body. The screenshot 202 reports a
+        // PENDING status (gateway src/routes/screenshots.ts:138) — not the queued status that
+        // `scrape create`'s envelope guard (commands/scrape.ts:49-53) tests for. Reusing that guard
+        // here would never fire in production and this branch would silently no-op. Grep gate G11
+        // (#2596) enforces the absence of a response-status discriminator in this file, which is why
+        // neither the symbol nor the comparison is spelled out above.
+        //
+        // The assignment sits INSIDE this branch, ahead of the `-o` return below, so `--async -o`
+        // carries the same exit code as bare `--async` (#2596 DoD 15 / E20). `--json` keeps exit 0:
+        // the envelope is a complete machine-readable payload, identical to scrape's split
+        // (scrape.ts:313-317). Soft `process.exitCode`, never `process.exit` — a hard exit runs
+        // before Node drains an async piped stdout and would truncate the envelope just written
+        // (#2544).
+        if (!opts.json)
+            process.exitCode = QUEUED_EXIT_CODE;
         return;
     }
     if (opts.output !== undefined) {
+        // A not-ready poll has no artifact to download — but the job WAS accepted and billed, so
+        // losing the handle behind a generic exit 1 is the defect (#2686 item 1). Mirror
+        // `scrape get --raw` on a queued envelope EXACTLY: the bare id on STDOUT (so
+        // `ss=$(bytekit screenshots get … -o -)` still captures a usable handle), a human note on
+        // STDERR, and QUEUED_EXIT_CODE. The `-o` file is deliberately never written — there is no
+        // image yet, and a file holding a bare id would masquerade as an artifact.
+        //
+        // Soft `process.exitCode`, never `process.exit`: a hard exit runs before Node drains an async
+        // piped stdout and would discard the very id this branch exists to deliver (#2544). Execution
+        // therefore continues past the assignment, so this branch must `return` explicitly — falling
+        // through to `extractImageUrl` would throw `not ready yet` and clobber the signal with exit 1.
+        const notReady = notReadyScreenshot(result);
+        if (notReady !== undefined) {
+            console.error(`Note: screenshot ${notReady.id} is ${notReady.status} — no image artifact is available ` +
+                `yet. Poll it with: bytekit screenshots get ${notReady.id}`);
+            process.stdout.write(`${notReady.id}\n`);
+            process.exitCode = QUEUED_EXIT_CODE;
+            return;
+        }
         await downloadArtifact(extractImageUrl(result), opts.output);
         return;
     }
@@ -89,11 +253,13 @@ export function makeScreenshotsCommand(getGlobal) {
         .option('--include-html', 'Include the rendered HTML alongside the screenshot')
         .option('--country <cc>', 'Two-letter country code to route the request through (e.g. us, de)')
         .option('--language <lang>', 'Accept-Language override (e.g. en-US)')
+        .option('--headers <json>', `Extra request headers as a JSON object, e.g. '{"X-A":"b"}' (omitted → none)`, (v) => parseJsonFlag('--headers', v, 'object'))
+        .option('--cookies <json>', `Cookies as a JSON array of {name,value,domain}, e.g. '[{"name":"a","value":"b","domain":"example.com"}]' (omitted → none)`, (v) => parseJsonFlag('--cookies', v, 'array'))
+        .option('--metadata <json>', `Arbitrary metadata echoed on the screenshot envelope, as a JSON object, e.g. '{"run":"7"}' (omitted → none)`, (v) => parseJsonFlag('--metadata', v, 'object'))
         .option('--async', 'Queue the screenshot and return a job envelope immediately (no wait)')
         .option('-o, --output <file>', 'Download the captured image to this file path (use - for stdout). Not valid with --json.')
         .action(async (opts) => {
         const g = getGlobal();
-        const client = buildClient(g);
         const body = { url: opts.url };
         // Each optional flag maps 1:1 to its snake_case ScreenshotRequest field, written ONLY when
         // present — a boolean never serializes `false` (#2480 E1).
@@ -135,7 +301,17 @@ export function makeScreenshotsCommand(getGlobal) {
             body['country'] = opts.country;
         if (opts.language !== undefined)
             body['language'] = opts.language;
+        // The server defaults headers/cookies/metadata to {} / [] / {}; writing an empty
+        // container on a bare create would materialize those defaults (#2480 E1).
+        if (opts.headers !== undefined)
+            body['headers'] = opts.headers;
+        if (opts.cookies !== undefined)
+            body['cookies'] = opts.cookies;
+        if (opts.metadata !== undefined)
+            body['metadata'] = opts.metadata;
         try {
+            // Inside the try: buildClient() throws on a missing key (#2686 item 4) and the throw must reach handleError(). See its doc comment in client.ts.
+            const client = buildClient(g);
             // Reject --json + -o BEFORE issuing the request: -o downloads BINARY artifact bytes, so
             // it can never coexist with --json (which must stay a text envelope). Thrown here so no
             // request — and therefore no download fetch — is ever issued (#2480 E2).
@@ -164,8 +340,9 @@ export function makeScreenshotsCommand(getGlobal) {
         .option('-o, --output <file>', 'Download the captured image to this file path (use - for stdout). Not valid with --json.')
         .action(async (id, opts) => {
         const g = getGlobal();
-        const client = buildClient(g);
         try {
+            // Inside the try: buildClient() throws on a missing key (#2686 item 4) and the throw must reach handleError(). See its doc comment in client.ts.
+            const client = buildClient(g);
             if (g.json && opts.output !== undefined) {
                 throw new Error('-o cannot be used with --json');
             }

package/dist/commands/search.js

@@ -49,7 +49,6 @@ export function makeSearchCommand(getGlobal) {
         .option('--date-range <window>', 'Restrict results to a recency window: any (default), hour, day, week, month, or year')
         .action(async (query, opts) => {
         const g = getGlobal();
-        const client = buildClient(g);
         // Build SearchOpts from the positional arg plus any provided flags.
         // Omit absent optionals so we never send undefined/NaN over the wire.
         // type/date_range are passed through verbatim; the API validates the
@@ -66,6 +65,8 @@ export function makeSearchCommand(getGlobal) {
         if (opts.dateRange !== undefined)
             body.date_range = opts.dateRange;
         try {
+            // Inside the try: buildClient() throws on a missing key (#2686 item 4) and the throw must reach handleError(). See its doc comment in client.ts.
+            const client = buildClient(g);
             const result = await client.search.query(body);
             if (g.json) {
                 printResult(result, true);

package/dist/commands/sitemap.js

@@ -1,7 +1,7 @@
 import { Command } from 'commander';
 import { buildClient } from '../client.js';
 import { printResult, handleError } from '../output.js';
-import { parseEnum, parseIntFlag } from '../lib/parse-flags.js';
+import { parseEnum, parseIntFlag, parseCacheTtl, parseJsonFlag } from '../lib/parse-flags.js';
 /** The `SitemapRequest.strategy` spec enum. */
 const SITEMAP_STRATEGIES = ['quick', 'standard', 'deep'];
 export function makeSitemapCommand(getGlobal) {
@@ -13,9 +13,17 @@ export function makeSitemapCommand(getGlobal) {
         .option('--strategy <strategy>', `Crawl strategy: ${SITEMAP_STRATEGIES.join(', ')} (omitted → server default standard)`, (v) => parseEnum('--strategy', SITEMAP_STRATEGIES, v))
         .option('--max-depth <n>', 'Maximum crawl depth 1-5 (omitted → server default 2)', (v) => parseIntFlag('--max-depth', v))
         .option('--max-urls <n>', 'Maximum URLs to collect (omitted → server default 5000)', (v) => parseIntFlag('--max-urls', v))
+        .option('--webhook-url <url>', 'HTTPS webhook URL notified when the crawl completes (omitted → poll-only, no delivery)')
+        .option('--webhook-secret <secret>', 'HMAC secret used to sign the completion webhook (omitted → unsigned)')
+        // Grammar-only validation, deliberately: sitemap caps cache_ttl at 90 DAYS
+        // (validators/sitemap.ts MAX_CACHE_TTL_SECONDS), not the 7d used by scrape/fetch. Mirroring
+        // the cap client-side would fork a second source of truth for a number only the server knows.
+        .option('--cache-ttl <ttl>', 'Cache freshness: 0, Nh (hours), or Nd (days), e.g. 48h, 30d, 0 (omitted → server default 30d; max 90d, enforced server-side)', (v) => parseCacheTtl('--cache-ttl', v))
+        .option('--compact', 'Return a compact result payload (omitted → server default off)')
+        .option('--process <json>', `Post-crawl processing directive as a JSON object, e.g. '{"action":"summarize"}' (omitted → none)`, (v) => parseJsonFlag('--process', v, 'object'))
+        .option('--metadata <json>', `Arbitrary metadata echoed on the job envelope, as a JSON object, e.g. '{"run":"7"}' (omitted → none)`, (v) => parseJsonFlag('--metadata', v, 'object'))
         .action(async (opts) => {
         const g = getGlobal();
-        const client = buildClient(g);
         // Omit-when-absent body; the remaining SitemapRequest fields keep their server defaults.
         // The generated request type marks defaulted fields required, so the call needs an explicit
         // assertion — type-level only; the wire body is pinned by request-shapes.test.ts.
@@ -26,7 +34,23 @@ export function makeSitemapCommand(getGlobal) {
             body['max_depth'] = opts.maxDepth;
         if (opts.maxUrls !== undefined)
             body['max_urls'] = opts.maxUrls;
+        if (opts.webhookUrl !== undefined)
+            body['webhook_url'] = opts.webhookUrl;
+        if (opts.webhookSecret !== undefined)
+            body['webhook_secret'] = opts.webhookSecret;
+        if (opts.cacheTtl !== undefined)
+            body['cache_ttl'] = opts.cacheTtl;
+        // `compact` server-defaults to FALSE, so it is written ONLY on `=== true` — writing
+        // `false` on a bare create would materialize a default (#2480 E1).
+        if (opts.compact === true)
+            body['compact'] = true;
+        if (opts.process !== undefined)
+            body['process'] = opts.process;
+        if (opts.metadata !== undefined)
+            body['metadata'] = opts.metadata;
         try {
+            // Inside the try: buildClient() throws on a missing key (#2686 item 4) and the throw must reach handleError(). See its doc comment in client.ts.
+            const client = buildClient(g);
             const result = await client.sitemap.create(body);
             printResult(result, g.json);
         }
@@ -39,8 +63,9 @@ export function makeSitemapCommand(getGlobal) {
         .description('Get a sitemap job by ID')
         .action(async (id) => {
         const g = getGlobal();
-        const client = buildClient(g);
         try {
+            // Inside the try: buildClient() throws on a missing key (#2686 item 4) and the throw must reach handleError(). See its doc comment in client.ts.
+            const client = buildClient(g);
             const result = await client.sitemap.get(id);
             printResult(result, g.json);
         }

package/dist/commands/usage.js

@@ -16,8 +16,9 @@ export function makeUsageCommand(getGlobal) {
         .description('Get current billing-period usage summary')
         .action(async () => {
         const g = getGlobal();
-        const client = buildClient(g);
         try {
+            // Inside the try: buildClient() throws on a missing key (#2686 item 4) and the throw must reach handleError(). See its doc comment in client.ts.
+            const client = buildClient(g);
             const result = await client.usage.get();
             printResult(result, g.json);
         }
@@ -33,7 +34,6 @@ export function makeUsageCommand(getGlobal) {
         .option('--api-key <ak_id>', 'Filter by API key prefixed ID (omitted → all keys)')
         .action(async (opts) => {
         const g = getGlobal();
-        const client = buildClient(g);
         const params = {};
         if (opts.from !== undefined)
             params.from = opts.from;
@@ -42,6 +42,8 @@ export function makeUsageCommand(getGlobal) {
         if (opts.apiKey !== undefined)
             params.api_key = opts.apiKey;
         try {
+            // Inside the try: buildClient() throws on a missing key (#2686 item 4) and the throw must reach handleError(). See its doc comment in client.ts.
+            const client = buildClient(g);
             const result = Object.keys(params).length > 0
                 ? await client.usage.daily(params)
                 : await client.usage.daily();
@@ -59,7 +61,6 @@ export function makeUsageCommand(getGlobal) {
         .option('--api-key <ak_id>', 'Filter by API key prefixed ID (omitted → all keys)')
         .action(async (opts) => {
         const g = getGlobal();
-        const client = buildClient(g);
         const params = {};
         if (opts.from !== undefined)
             params.from = opts.from;
@@ -68,6 +69,8 @@ export function makeUsageCommand(getGlobal) {
         if (opts.apiKey !== undefined)
             params.api_key = opts.apiKey;
         try {
+            // Inside the try: buildClient() throws on a missing key (#2686 item 4) and the throw must reach handleError(). See its doc comment in client.ts.
+            const client = buildClient(g);
             const result = Object.keys(params).length > 0
                 ? await client.usage.byEndpoint(params)
                 : await client.usage.byEndpoint();

package/dist/commands/webhook-deliveries.js

@@ -21,7 +21,6 @@ export function makeWebhookDeliveriesCommand(getGlobal) {
         .option('--since <iso>', 'Only deliveries created after this ISO date-time')
         .action(async (opts) => {
         const g = getGlobal();
-        const client = buildClient(g);
         const params = {};
         if (opts.limit !== undefined)
             params.limit = opts.limit;
@@ -32,6 +31,8 @@ export function makeWebhookDeliveriesCommand(getGlobal) {
         if (opts.since !== undefined)
             params.since = opts.since;
         try {
+            // Inside the try: buildClient() throws on a missing key (#2686 item 4) and the throw must reach handleError(). See its doc comment in client.ts.
+            const client = buildClient(g);
             const result = Object.keys(params).length > 0
                 ? await client.webhooks.list(params)
                 : await client.webhooks.list();
@@ -46,8 +47,9 @@ export function makeWebhookDeliveriesCommand(getGlobal) {
         .description('Requeue a failed or exhausted webhook delivery')
         .action(async (id) => {
         const g = getGlobal();
-        const client = buildClient(g);
         try {
+            // Inside the try: buildClient() throws on a missing key (#2686 item 4) and the throw must reach handleError(). See its doc comment in client.ts.
+            const client = buildClient(g);
             const result = await client.webhooks.retry(id);
             printResult(result, g.json);
         }

package/dist/lib/download-artifact.d.ts

@@ -9,5 +9,34 @@
  * test that stubs `globalThis.fetch` in a `beforeEach` — after this module was imported — still
  * sees its stub (G-049). A non-2xx response throws with the HTTP status so `handleError` renders a
  * clean one-liner and exits 1.
+ *
+ * TIMEOUT (#2587): this path sat entirely outside the transport seam — no abort signal, no
+ * connection-error taxonomy — so a stalled artifact host (headers, then a body that never
+ * completes) hung the CLI forever, even though the 0.5.0 CHANGELOG's "a stalled body hung the CLI
+ * forever" note (#2546) reads as if every response body were covered. #2546 only covered API-call
+ * bodies read through `sendWithRetry`; this download never rode that seam. The fix REUSES
+ * `sendWithRetry`'s own per-attempt abort budget and connection-error taxonomy
+ * (`createAttemptBudget` / `toConnectionError`, exported from `../client.js`) rather than a second
+ * timeout implementation, and mirrors the same default (`DEFAULT_TIMEOUT_MS`, 120 s per attempt) —
+ * there is no retry here, since artifact GETs are not the API's 429 domain.
+ *
+ * PARTIAL-FILE POLICY (#2587 dod-1 / E1, decided + recorded, scoped to the DOWNLOAD phase only —
+ * cr-4): the response is buffered COMPLETELY in memory (`res.arrayBuffer()`) before either write
+ * path (`writeFileSync` / `process.stdout.write`) runs, so an ABORT — whether from the timeout or
+ * any other connection failure — always fails BEFORE a single byte is written; no partial file is
+ * ever left at `dest` from a download-side failure. This does NOT cover a failure DURING the write
+ * itself: `writeFileSync` opens `dest` with `O_TRUNC` and writes in a loop, so e.g. an `ENOSPC`
+ * partway through a large write leaves a created, truncated file at `dest` (any pre-existing file
+ * there already clobbered by the `O_TRUNC` open). That failure mode is accepted as-is for now (no
+ * write-to-temp-then-`renameSync` here) — the CLI still exits 1, and the write phase's tiny
+ * (post-buffering) failure window is a separate, unaddressed edge from the abort guarantee above.
+ *
+ * @param timeoutMs Per-attempt abort budget in ms; defaults to {@link DEFAULT_TIMEOUT_MS} (120 s).
+ *   `<= 0` DISABLES the budget entirely (no `AbortSignal` is attached, restoring the exact
+ *   unbounded-hang behavior this ticket fixes) rather than meaning "no override" — there is no
+ *   sentinel for that. #2587 cr-8: no CLI command reaches this parameter today
+ *   (`commands/screenshots.ts` always calls the 2-arg form), so a future caller — e.g. an
+ *   anticipated `--timeout` flag threaded through here — must NOT pass `0` to mean "use the
+ *   default"; it must omit the argument or pass `DEFAULT_TIMEOUT_MS` explicitly.
  */
-export declare function downloadArtifact(url: string, dest: string): Promise<void>;
+export declare function downloadArtifact(url: string, dest: string, timeoutMs?: number): Promise<void>;

package/dist/lib/download-artifact.js

@@ -1,4 +1,25 @@
 import { writeFileSync } from 'node:fs';
+import { createAttemptBudget, toConnectionError, DEFAULT_TIMEOUT_MS } from '../client.js';
+/**
+ * Redact a URL for error-message rendering: origin + pathname only, query string dropped.
+ *
+ * #2587 cr-2: `image_url` for a completed screenshot is an AWS SigV4 PRESIGNED URL
+ * (`X-Amz-Credential=…&X-Amz-Signature=…`, `gateway/src/lib/signed-url.ts`), unlike every other
+ * `toConnectionError` call site in `client.ts` which passes a bare relative API path with no
+ * credential material. Rendering the full URL in `handleError`'s unmodified `err.message` would
+ * print a live 600s-valid signature to stderr on every new failure path this diff adds. On a
+ * malformed URL (should not happen — `image_url` is always an absolute URL from the API) fall
+ * back to the original string rather than throwing out of an error-handling path.
+ */
+function redactedPath(url) {
+    try {
+        const u = new URL(url);
+        return `${u.origin}${u.pathname}`;
+    }
+    catch {
+        return url;
+    }
+}
 /**
  * Download a screenshot artifact from its `image_url` and write the raw bytes to `dest`.
  *
@@ -10,13 +31,77 @@ import { writeFileSync } from 'node:fs';
  * test that stubs `globalThis.fetch` in a `beforeEach` — after this module was imported — still
  * sees its stub (G-049). A non-2xx response throws with the HTTP status so `handleError` renders a
  * clean one-liner and exits 1.
+ *
+ * TIMEOUT (#2587): this path sat entirely outside the transport seam — no abort signal, no
+ * connection-error taxonomy — so a stalled artifact host (headers, then a body that never
+ * completes) hung the CLI forever, even though the 0.5.0 CHANGELOG's "a stalled body hung the CLI
+ * forever" note (#2546) reads as if every response body were covered. #2546 only covered API-call
+ * bodies read through `sendWithRetry`; this download never rode that seam. The fix REUSES
+ * `sendWithRetry`'s own per-attempt abort budget and connection-error taxonomy
+ * (`createAttemptBudget` / `toConnectionError`, exported from `../client.js`) rather than a second
+ * timeout implementation, and mirrors the same default (`DEFAULT_TIMEOUT_MS`, 120 s per attempt) —
+ * there is no retry here, since artifact GETs are not the API's 429 domain.
+ *
+ * PARTIAL-FILE POLICY (#2587 dod-1 / E1, decided + recorded, scoped to the DOWNLOAD phase only —
+ * cr-4): the response is buffered COMPLETELY in memory (`res.arrayBuffer()`) before either write
+ * path (`writeFileSync` / `process.stdout.write`) runs, so an ABORT — whether from the timeout or
+ * any other connection failure — always fails BEFORE a single byte is written; no partial file is
+ * ever left at `dest` from a download-side failure. This does NOT cover a failure DURING the write
+ * itself: `writeFileSync` opens `dest` with `O_TRUNC` and writes in a loop, so e.g. an `ENOSPC`
+ * partway through a large write leaves a created, truncated file at `dest` (any pre-existing file
+ * there already clobbered by the `O_TRUNC` open). That failure mode is accepted as-is for now (no
+ * write-to-temp-then-`renameSync` here) — the CLI still exits 1, and the write phase's tiny
+ * (post-buffering) failure window is a separate, unaddressed edge from the abort guarantee above.
+ *
+ * @param timeoutMs Per-attempt abort budget in ms; defaults to {@link DEFAULT_TIMEOUT_MS} (120 s).
+ *   `<= 0` DISABLES the budget entirely (no `AbortSignal` is attached, restoring the exact
+ *   unbounded-hang behavior this ticket fixes) rather than meaning "no override" — there is no
+ *   sentinel for that. #2587 cr-8: no CLI command reaches this parameter today
+ *   (`commands/screenshots.ts` always calls the 2-arg form), so a future caller — e.g. an
+ *   anticipated `--timeout` flag threaded through here — must NOT pass `0` to mean "use the
+ *   default"; it must omit the argument or pass `DEFAULT_TIMEOUT_MS` explicitly.
  */
-export async function downloadArtifact(url, dest) {
-    const res = await globalThis.fetch(url);
-    if (!res.ok) {
-        throw new Error(`artifact download failed: HTTP ${res.status}`);
+export async function downloadArtifact(url, dest, timeoutMs = DEFAULT_TIMEOUT_MS) {
+    const budget = timeoutMs > 0 ? createAttemptBudget(timeoutMs) : undefined;
+    const safePath = redactedPath(url);
+    let bytes;
+    try {
+        let res;
+        try {
+            res = await globalThis.fetch(url, budget ? { signal: budget.signal } : {});
+        }
+        catch (err) {
+            // No HTTP response was produced (timeout, abort, socket/DNS/TLS) — re-throw as the SDK's own
+            // ByteKitConnectionError, exactly like the API transport, so a hung/broken artifact host can
+            // never hang the CLI and `handleError` renders the same taxonomy either way. `safePath` (not
+            // `url`) is what gets rendered — see {@link redactedPath}.
+            throw toConnectionError(err, 'GET', safePath, budget?.signal.aborted === true);
+        }
+        if (!res.ok) {
+            // #2587 cr2-1: no drain here, unlike client.ts's 429 path. cr-11 originally added one
+            // (mirroring client.ts's corrected 429-drain mechanism, cr-3), reasoning that a full
+            // `text()` read lets undici return the connection to the pool. That reasoning does not
+            // apply on THIS path: `commands/screenshots.ts` throws this error straight into
+            // `handleError`, which is the last statement of the action's catch — the command then ends
+            // (signalling exit 1 via `process.exitCode` since #2686 item 4), so there is no next request
+            // in this process for a reclaimed socket to serve. A drain here was bounded only by the FULL
+            // per-attempt abort budget (or, under `timeoutMs <= 0`, by nothing at all) for zero benefit,
+            // so it is removed outright rather than merely capped.
+            throw new Error(`artifact download failed: HTTP ${res.status}`);
+        }
+        try {
+            bytes = Buffer.from(await res.arrayBuffer());
+        }
+        catch (err) {
+            // A body read that never completes is aborted by the same budget; undici then rejects the
+            // stream (mirrors #2546's body-read guard). Map it into the same taxonomy as above.
+            throw toConnectionError(err, 'GET', safePath, budget?.signal.aborted === true);
+        }
+    }
+    finally {
+        // Clear the timer on every exit path so a healthy download leaves no dangling budget timer.
+        budget?.cleanup();
     }
-    const bytes = Buffer.from(await res.arrayBuffer());
     if (dest === '-') {
         process.stdout.write(bytes);
         return;

package/dist/lib/parse-flags.js

@@ -69,7 +69,9 @@ export function parseJsonFlag(flag, value, expect) {
         parsed = JSON.parse(value);
     }
     catch {
-        throw new InvalidArgumentError(`${flag} must be valid JSON (a ${expect}), e.g. '${example}'.`);
+        // "an", not "a": both shape words (`object`, `array`) begin with a vowel, so a hardcoded
+        // article read `(a object)` / `(a array)` (#2686 item 5).
+        throw new InvalidArgumentError(`${flag} must be valid JSON (an ${expect}), e.g. '${example}'.`);
     }
     const matches = expect === 'array'
         ? Array.isArray(parsed)

package/dist/lib/url-lines.d.ts

@@ -1,12 +1,50 @@
 /**
- * Read a newline-delimited file of URLs and return a flat array of URL strings.
+ * One parsed `--file` line: a bare URL string, or a per-item config object carrying `url`.
  *
- * Each non-blank line is either a plain URL or a JSON object of the form
- * `{"url":"https://..."}`. Both forms normalize to the bare URL string, because
- * the v1 bulk endpoints (`/v1/bulk`, `/v1/scrape/bulk`, `/v1/fetch/bulk`) expect
- * `urls` to be an array of URL strings — NOT an array of objects.
+ * The two arms are not interchangeable on the wire. `/v1/bulk` and `/v1/scrape/bulk` accept
+ * `urls` (strings) XOR `items` (objects); `/v1/fetch/bulk` has no `items` property at all and
+ * takes a heterogeneous `urls` union. Callers pick the right shape — see {@link toBulkItems}.
+ */
+export type BulkLine = string | Record<string, unknown>;
+/**
+ * Read a newline-delimited `--file` and return one {@link BulkLine} per non-blank line.
+ *
+ * Line grammar:
+ * - a non-JSON line                            -> the raw line (a plain URL string)
+ * - a JSON object whose ONLY key is `url`      -> the bare url string
+ * - a JSON object carrying other keys too      -> the object verbatim (per-item config)
+ * - a JSON object with a missing/non-string url -> `InvalidArgumentError` (rejected locally)
+ * - a JSON non-object (number, array, string)  -> the raw line
+ *
+ * The "only key is `url`" arm is what keeps the inverse case BYTE-IDENTICAL rather than merely
+ * equivalent: a file of url-only lines produces the exact same `{ urls, webhook_url }` body as
+ * before per-item config existed (#2596 E2).
+ *
+ * Rejecting a malformed `url` is a deliberate behavior change (#2596 DoD 8). The previous parser
+ * fell through to the raw line, so `{"url": 123}` was sent to the server AS a URL — a confusing
+ * 422 for what is a local input mistake. `InvalidArgumentError` surfaces through the same
+ * local-usage-error path as every argParser rejection (exit 1), before any request is issued.
+ *
+ * Throws on a missing file (ENOENT from readFileSync) — callers surface this via their
+ * handleError path.
+ *
+ * The rejection message for a malformed line (#2596 cr-1 / E12) names the 1-based PHYSICAL line
+ * NUMBER (i.e. the line's own position in the file, counting blank lines) and the line's own KEY
+ * NAMES only — never the raw line or any value. A `--file` line is where per-item `cookies`,
+ * `headers`, and auth-bearing `metadata` now live (#2596), so echoing the raw line back would
+ * leak session tokens and similar secrets to stderr, CI logs, and shell transcripts. Because the
+ * raw line is deliberately never echoed, the line number is the ONLY locator left in the message —
+ * it must be computed BEFORE blank lines are filtered out, or it silently mis-locates the bad
+ * entry whenever the file contains blank lines above it (#2596 cr-2).
+ */
+export declare function parseBulkLines(file: string): BulkLine[];
+/**
+ * Promote every {@link BulkLine} to the `items[]` object shape used by `/v1/bulk` and
+ * `/v1/scrape/bulk`.
  *
- * Throws on a missing file (ENOENT from readFileSync) — callers surface this via
- * their handleError path.
+ * Deliberately stamps NOTHING beyond `url`. `/v1/bulk` owns capture-kind precedence server-side
+ * (per-item value, then `defaults`, then the endpoint default) since #2641 made the per-item
+ * field optional; a CLI-side default would silently override a caller's `--defaults` and is
+ * grep-gated out (#2596 G7).
  */
-export declare function parseUrlLines(file: string): string[];
+export declare function toBulkItems(lines: BulkLine[]): Array<Record<string, unknown>>;