@hunt-labs/bytekit-cli 0.8.0 → 0.9.0

package/CHANGELOG.md

@@ -10,6 +10,100 @@ today, see [README.md](./README.md), which remains the authoritative usage guide
 
 ## [Unreleased]
 
+## [0.9.0] - 2026-08-20
+
+### Removed
+
+- **BREAKING: `--cookies` and `--headers` are gone from `scrape create` and `screenshots create`**
+  (#3242). The API no longer accepts caller-supplied cookies or request headers on any capture
+  endpoint, so passing either flag is now an unknown-option error before any request is issued,
+  and a body carrying those keys is rejected by the server with `400 validation_error`. There is
+  no deprecation window, feature flag, or compatibility header.
+
+  ```bash
+  # before
+  bytekit scrape create --url https://example.com --cookies '[{"name":"session","value":"abc"}]'
+  # after — the flag does not exist
+  bytekit scrape create --url https://example.com
+  ```
+
+  `--webhook-headers` on `monitors` is a different flag and is unaffected.
+
+## [0.8.1] - 2026-08-13
+
+### Fixed
+
+- **`bytekit search` explains a malformed `200` instead of leaking a `TypeError`.** A server
+  answering `200 {"ok":true}` — a proxy, a stub, a future envelope change — drove the human-mode
+  renderer into `Error: response.results is not iterable`, which named an internal expression
+  rather than the field the body was missing. It now reports, on one line and with no stack trace,
+  `search: the response carries no "results" array — the server returned an unexpected 200 body. Re-run with --json to inspect it.`
+  and exits `1`. A `results` value that is present but not an array is caught by the same gate: a
+  **string** was previously iterated CHARACTER BY CHARACTER, printing one garbled row per character
+  and exiting `0`. Unchanged: an empty `results: []` is still a successful zero-hit search that
+  prints nothing and exits `0`; valid responses render byte-identically; and `--json` never reaches
+  the renderer, so it keeps dumping the raw body at exit `0` — which is how you inspect an
+  unexpected body.
+
+### Added
+
+- **`screenshots … -o <file>` now says so when the filename contradicts the captured format.**
+  `--format` is omitted far more often than not and the server default is **jpeg**, so
+  `bytekit screenshots create --url … -o shot.png` wrote JPEG bytes into a `.png`-named file
+  silently, at exit `0`; `screenshots get` has no `--format` flag at all, so it could not even be
+  told what it was downloading. Both now print one advisory line to **stderr** —
+  `Note: the screenshot was captured as jpeg, but shot.png names .png. The file holds jpeg bytes — pass --format png to capture it as png.`
+  The captured format is read from the artifact URL's own path, which is the only place the CLI can
+  observe it. **Advisory, not enforcement:** the bytes written and the exit code are unchanged, and
+  the note goes to stderr, so `-o -` pipelines and stdout redirects stay byte-identical. It stays
+  silent unless both the destination and the artifact name a recognized image format and the two
+  differ — `.jpg` and `.jpeg` are the same format, and an extension-less destination, a non-image
+  extension, `-o -`, or an artifact URL with no usable extension all make no claim to contradict. A
+  not-ready poll is untouched: it still prints its bare id and poll note at exit `2`.
+
+### Changed
+
+- **The README now documents the whole flag surface, and says which reference wins.** Every flag
+  worked and every flag appeared in `--help`; the README simply framed subsets as exhaustive, so
+  `bulk create`'s `--webhook-secret` / `--defaults` / `--metadata`, `scrape bulk create`'s
+  `--custom`, `sitemap create`'s `--webhook-url` / `--webhook-secret` / `--cache-ttl` /
+  `--compact` / `--process` / `--metadata`, `monitors create` and `monitors update`'s `--cron`
+  (required with `--interval-type cron`) and `--metadata` plus the rest of `update`'s surface,
+  `fetch create`'s ten markdown flags and `--custom`, and `screenshots create`'s `--headers` /
+  `--cookies` / `--metadata` were all undocumented. All of them are documented now, and a note at
+  the top of the README states that `--help` is the authoritative flag reference. **Required flags
+  are marked as such** — `--file` and `--webhook-url` on all three bulk creators, `--url` /
+  `--interval-type` / `--webhook-url` on `monitors create`, and `--url` on `scrape create`,
+  `screenshots create`, `sitemap create` and both `fetch` verbs — so no reader mistakes one for
+  optional. Note in particular that a **bulk job has no poll-only mode**: `--webhook-url` is
+  mandatory there, unlike on `sitemap create` where omitting it really does mean poll-only. A test
+  asserts the parity in the direction that matters — every flag the parser accepts must appear in
+  the README — so this cannot drift again silently. No command, flag or behavior changed.
+
+- **Alignment-release note, carried forward from this version's original cut.** `0.8.0` published
+  to npm at `2026-08-11T21:18:01.304Z`. Doc comments in `src/client.ts` and
+  `src/package-version.ts` were reworded **after** the commit that introduced the `0.8.0` version
+  string — they had re-spelled the `X-ByteKit-Client` header name in prose, which issue #2906's
+  pre-merge gate 1 counts. No command, flag, exit code, or runtime behavior differs from `0.8.0`
+  on account of _those_ comments.
+
+  `0.8.1` was cut for that reason because `check-release-drift` (#2680) is version-gated and
+  anchors on the commit that introduced a version, not on the commit whose tree was actually
+  published. Once `0.8.0` reached npm, any shipped-file change after that anchor reads as
+  post-release drift. Bumping moves the anchor past those comments. `0.8.1` had not yet reached
+  npm when the entries above landed, so they ride this same pending release rather than stranding
+  it as a never-published version.
+
+- **Corrected a false legacy-name claim carried since the rename (#2950).** The `0.8.0`-era note
+  below said the prior `rapidcrawl-cli` name "remains installable at its last version but is
+  deprecated." Verified 2026-08-13: `rapidcrawl-cli` returns npm `404` ("is not in this
+  registry"), and `npm deprecate rapidcrawl-cli@'*'` fails with the same `404` — there is no
+  published version left for a deprecation notice to attach to, so the claim never held. No
+  registry stub or deprecation was possible to publish (npm has nothing to act on); root
+  `CLAUDE.md` carried the same false claim and is corrected alongside this entry. Users of the old
+  name should install `@hunt-labs/bytekit-cli` directly. No command, flag, or runtime behavior
+  changes.
+
 ## [0.8.0] - 2026-08-11
 
 ### Added
@@ -446,14 +540,16 @@ Additive, lower-risk release — no breaking changes to existing commands.
 ### Changed
 
 - Package renamed to `@hunt-labs/bytekit-cli` (the `@bytekit` npm scope was
-  unobtainable); the `bin` name stays `bytekit`. The prior `rapidcrawl-cli` name
-  remains installable at its last version but is deprecated.
+  unobtainable); the `bin` name stays `bytekit`. ~~The prior `rapidcrawl-cli` name
+  remains installable at its last version but is deprecated.~~ **Corrected in
+  0.8.1 (see below): that claim does not hold — `rapidcrawl-cli` 404s on npm and
+  there is no published version left to deprecate.**
 - Consumer call sites propagate the SDK's narrowed, spec-derived request types (#2426).
 - Publish-ready packaging metadata: dropped `main`, unpinned the SDK dependency to
   `workspace:^`, added `engines`, `keywords`, `homepage`, `bugs`, `README.md`,
   `LICENSE`, and an MIT `license` field.
 
-## [0.1.0] - 2026
+## [0.1.0] - 2026-07-13
 
 ### Added
 

package/README.md

@@ -4,6 +4,12 @@ Command-line interface for the [ByteKit](https://bytekit.com) API — scrape,
 fetch, screenshot, search, crawl sitemaps, and manage page monitors from your
 shell. Wraps [`@hunt-labs/bytekit-sdk`](https://www.npmjs.com/package/@hunt-labs/bytekit-sdk).
 
+> **`--help` is the authoritative flag reference.** Every command and subcommand
+> accepts it — `bytekit sitemap create --help`, `bytekit monitors update --help` —
+> and the list it prints is generated from the code that parses your argv, so it
+> is never out of date. This README documents the same surface in prose for
+> reading; where the two ever disagree, `--help` is right.
+
 ## Install
 
 ```bash
@@ -86,9 +92,13 @@ bytekit scrape get sc_123abc
 bytekit scrape bulk create --file urls.txt --webhook-url https://your.app/hooks/bytekit
 ```
 
-`scrape create` also accepts the full `ScrapeRequest` surface, each flag omitted
-from the request when absent (a boolean flag never sends `false`, so a server
-default is never materialized):
+`scrape bulk create` takes the shared bulk-job flags plus `--custom` — see
+[`bulk`](#bulk--bulk-screenshot-jobs).
+
+`scrape create` **requires** `--url <url>`. It also accepts the full
+`ScrapeRequest` surface below, each of those flags omitted from the request when
+absent (a boolean flag never sends `false`, so a server default is never
+materialized):
 
 | Flag                                                   | Effect                                                                                                                                                                                             |
 | ------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -161,7 +171,7 @@ exits `0`.
 
 ```bash
 bytekit fetch create --url https://example.com
-bytekit fetch get --url https://example.com --format markdown
+bytekit fetch get --url https://example.com
 bytekit fetch get --url https://example.com/logo.png -o logo.png
 bytekit fetch bulk create --file urls.txt --webhook-url https://your.app/hooks/bytekit
 ```
@@ -183,9 +193,14 @@ Note the acronym casing — `X-Fetch-ID` and `X-Fetch-URL`, not `X-Fetch-Id` /
 `X-Fetch-Url`. (Versions up to 0.6.0 emitted the Title-Cased spellings; see the
 CHANGELOG.)
 
-Both verbs accept `--country <cc>`, `--timeout-ms <n>`, and `--cache-ttl <ttl>`
-(`0`, `Nh`, or `Nd`), each omitted when absent. `--markdown-mode`
-(`article`, `raw`, `llm`) is `fetch create` only.
+Both verbs **require** `--url <url>`. They accept `--country <cc>`, `--timeout-ms <n>`, `--cache-ttl <ttl>`
+(`0`, `Nh`, or `Nd`), and `-o, --output <file>` — each of those omitted from the
+request when absent.
+
+`fetch create` and `fetch get` send only the raw-fetch options listed above.
+
+`fetch bulk create` takes the shared bulk-job flags — see
+[`bulk`](#bulk--bulk-screenshot-jobs).
 
 ### `search` — ranked web search
 
@@ -206,7 +221,8 @@ bytekit screenshots create --url https://example.com --device mobile --format pn
 bytekit screenshots get ss_123abc -o shot.png
 ```
 
-`screenshots create` accepts `--device` (`desktop`, `mobile`), `--viewport WxH`
+`screenshots create` **requires** `--url <url>`. It also accepts `--device`
+(`desktop`, `mobile`), `--viewport WxH`
 (e.g. `1280x720`), `--format` (`jpeg`, `png`), `--quality <n>`, `--wait-until`
 (`load`, `domcontentloaded`, `networkidle`), `--clip x,y,w,h`, and `--async`
 (queue and return a job envelope). Each flag is omitted from the request when
@@ -214,7 +230,10 @@ absent.
 
 It also accepts `--wait-for-selector <sel>`, `--delay-ms <n>`,
 `--device-scale-factor` (`1` or `2`), `--dark-mode`, `--include-html`,
-`--country <cc>`, `--language <lang>`, and three **tri-state** blocker pairs:
+`--country <cc>`, `--language <lang>`, three JSON flags — `--headers <json>`
+(extra request headers as an object, e.g. `'{"X-A":"b"}'`), `--cookies <json>`
+(an array of `{name,value,domain}`), and `--metadata <json>` (echoed back on the
+screenshot envelope) — and three **tri-state** blocker pairs:
 `--block-ads` / `--no-block-ads`, `--block-cookie-banners` /
 `--no-block-cookie-banners`, and `--scroll` / `--no-scroll`. Each of these three
 defaults to `true` server-side, so passing neither half omits the key entirely
@@ -227,6 +246,23 @@ stdout). Because `-o` writes BINARY on `screenshots`, it cannot be combined with
 `--async` + `-o` prints the queued job envelope and skips the download (the
 image is not ready yet).
 
+**`-o` never converts — it names the file, `--format` names the bytes.** The
+server default format is **jpeg**, so `-o shot.png` on a capture that did not
+pass `--format png` writes JPEG bytes into a `.png`-named file. When the
+destination's extension and the captured format disagree, the CLI prints one
+advisory line to stderr and downloads anyway:
+
+```text
+Note: the screenshot was captured as jpeg, but shot.png names .png.
+The file holds jpeg bytes — pass --format png to capture it as png.
+```
+
+The bytes written and the exit code are unchanged — it is a note, not a refusal,
+and it goes to stderr so `-o -` pipelines and stdout redirects stay
+byte-identical. It stays silent when the two agree (`.jpg` and `.jpeg` are the
+same format), and when the destination makes no format claim at all (`-o -`, no
+extension, or a non-image extension).
+
 ### `bulk` — bulk screenshot jobs
 
 ```bash
@@ -237,8 +273,36 @@ bytekit bulk cancel "$bulk_id"
 bytekit bulk screenshots list "$bulk_id"
 ```
 
-`urls.txt` is newline-delimited: one plain URL (or `{"url":"https://..."}`) per line.
-`bulk cancel <id>` stops an in-flight job.
+`urls.txt` is newline-delimited: one plain URL (or `{"url":"https://..."}`) per
+line. A line whose only key is `url` is sent as a bare URL string; any line with
+additional keys switches that entry to the per-item shape. `bulk cancel <id>`
+stops an in-flight job; `bulk get <id>` and `bulk screenshots list <id>` take no
+flags.
+
+The three bulk-job creators — `bulk create`, `scrape bulk create` and
+`fetch bulk create` — share one flag set:
+
+| Flag                        | Effect                                                                                                 |
+| --------------------------- | ------------------------------------------------------------------------------------------------------ |
+| `--file <path>`             | **Required.** The newline-delimited input file described above.                                        |
+| `--webhook-url <url>`       | **Required.** HTTPS webhook notified when the job completes.                                           |
+| `--webhook-secret <secret>` | HMAC secret used to sign that completion webhook. Omitted → unsigned.                                  |
+| `--defaults <json>`         | Defaults applied to every entry, as a JSON object. Omitted → none.                                     |
+| `--metadata <json>`         | Arbitrary metadata echoed on the job envelope, as a JSON object, e.g. `'{"run":"7"}'`. Omitted → none. |
+
+A bulk job has **no poll-only mode**. `--file` and `--webhook-url` are both
+required on all three creators — omitting either is a usage error raised before
+any request is sent (`error: required option '--webhook-url <url>' not
+specified`), and the API declares `webhook_url` required as well. The three
+optional flags are omitted from the request when absent.
+
+`--defaults` is validated differently per endpoint: `bulk` rejects unknown keys
+with a `422`, while `scrape bulk` and `fetch bulk` ignore them — and `fetch bulk`
+additionally rejects the browser-only keys (`cookies`, `wait_until`,
+`wait_for_selector`, `delay_ms`) with a `400`.
+
+`scrape bulk create` adds one flag the other two do not have: `--custom <json>`,
+a user payload echoed on every scrape entry (a per-entry value in `--file` wins).
 
 ### `monitors` — watch a page for changes
 
@@ -260,14 +324,34 @@ each omitted when absent.
 page through a monitor's capture history — pass the response's `next_cursor`
 back as `--cursor` to fetch the next page. Both flags are omitted when absent.
 
-`monitors update` gains `--status` (`active` | `paused` — pause and resume from
-the shell), `--change-threshold <pct>` (accepts a float), `--notify-on`
-(`change`, `every`), `--webhook-secret <secret>`, and three JSON-object flags:
-`--webhook-headers`, `--options`, and `--scrape-options` (e.g.
-`--options '{"device":"mobile"}'`). `monitors create` accepts the same set plus
-`--type` (`screenshot` | `scrape`). `--type` is **create-only** — a monitor's
-type is immutable, so `monitors update` deliberately has no `--type`. Every flag
-is omitted from the request when absent.
+`monitors create` and `monitors update` share almost all of their flags. On
+`update` every one is optional and omitted from the request when absent, so
+`monitors update` changes only what you name. Three are **required on `create`**
+and marked below:
+
+| Flag                        | Effect                                                                                     |
+| --------------------------- | ------------------------------------------------------------------------------------------ |
+| `--url <url>`               | **Required on `create`.** URL to monitor.                                                  |
+| `--interval-type <type>`    | **Required on `create`.** Check interval: `hourly`, `daily`, `weekly`, or `cron`.          |
+| `--cron <expr>`             | Cron expression — **required** when `--interval-type` is `cron`, e.g. `'0 * * * *'`.       |
+| `--webhook-url <url>`       | **Required on `create`.** HTTPS webhook notified on change.                                |
+| `--change-threshold <pct>`  | Change percentage that triggers a notification (accepts a float).                          |
+| `--notify-on <event>`       | When to notify: `change`, `every`.                                                         |
+| `--webhook-secret <secret>` | HMAC secret for webhook signature verification.                                            |
+| `--webhook-headers <json>`  | Extra webhook headers as a JSON object, e.g. `'{"X-Sig":"abc"}'`.                          |
+| `--options <json>`          | Screenshot-monitor options as a JSON object, e.g. `--options '{"device":"mobile"}'`.       |
+| `--scrape-options <json>`   | Scrape-monitor options as a JSON object (`--type scrape` only).                            |
+| `--metadata <json>`         | Arbitrary metadata echoed on the monitor envelope, as a JSON object, e.g. `'{"run":"7"}'`. |
+
+Two flags are not shared. `--type` (`screenshot` | `scrape`) is **create-only** —
+a monitor's type is immutable, so `monitors update` deliberately has none.
+`--status` (`active` | `paused`, to pause and resume from the shell) is
+**update-only**.
+
+```bash
+bytekit monitors create --url https://example.com/pricing --interval-type cron \
+  --cron '0 * * * *' --webhook-url https://your.app/hooks/bytekit
+```
 
 ### `sitemap` — crawl a site's URL graph
 
@@ -276,8 +360,24 @@ bytekit sitemap create --url https://example.com --strategy deep --max-depth 3 -
 bytekit sitemap get sm_123abc
 ```
 
-`sitemap create` accepts `--strategy` (`quick`, `standard`, `deep`),
-`--max-depth <n>`, and `--max-urls <n>`, each omitted when absent.
+`sitemap get <id>` takes no flags. `sitemap create` accepts:
+
+| Flag                        | Effect                                                                                                                                  |
+| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| `--url <url>`               | **Required.** Root URL to crawl.                                                                                                        |
+| `--strategy <strategy>`     | Crawl strategy: `quick`, `standard`, `deep`. Omitted → server default `standard`.                                                       |
+| `--max-depth <n>`           | Maximum crawl depth, 1–5. Omitted → server default `2`.                                                                                 |
+| `--max-urls <n>`            | Maximum URLs to collect. Omitted → server default `5000`.                                                                               |
+| `--webhook-url <url>`       | HTTPS webhook notified when the crawl completes. Omitted → poll-only, no delivery.                                                      |
+| `--webhook-secret <secret>` | HMAC secret used to sign that completion webhook. Omitted → unsigned.                                                                   |
+| `--cache-ttl <ttl>`         | Cache freshness: `0`, `Nh` (hours), or `Nd` (days), e.g. `48h`, `30d`. Omitted → server default `30d`; max `90d`, enforced server-side. |
+| `--compact`                 | Return a compact result payload. Omitted → server default off.                                                                          |
+| `--process <json>`          | Post-crawl processing directive as a JSON object, e.g. `'{"action":"summarize"}'`. Omitted → none.                                      |
+| `--metadata <json>`         | Arbitrary metadata echoed on the job envelope, as a JSON object, e.g. `'{"run":"7"}'`. Omitted → none.                                  |
+
+Only `--url` is required; every other flag is omitted from the request when
+absent. Unlike a bulk job, a sitemap crawl really is poll-only without
+`--webhook-url`.
 
 ### `account` — account details
 

package/dist/commands/fetch.d.ts

@@ -1,19 +1,5 @@
 import { Command } from 'commander';
 import { type GlobalOptions } from '../client.js';
-/** The `/v1/fetch` spec union for `format` — mirrors `FetchOpts['format']` in the SDK. */
-type FetchFormat = 'markdown' | 'html';
-/**
- * Validate `--format` locally, before any HTTP request is issued.
- *
- * The SDK's `FetchOpts.format` is narrowed to the spec union `'markdown' | 'html'`
- * (#2475), so an off-spec value like `pdf` is a compile-time error at the call site.
- * Commander runs an option's argParser during parsing — ahead of the action callback —
- * so rejecting here means the client is never built and no request is issued, and the
- * caller gets an actionable message instead of a server 422 (same convention as
- * `parseLimit` in search.ts).
- */
-export declare function parseFormat(value: string): FetchFormat;
 export declare function makeFetchCommand(getGlobal: () => GlobalOptions & {
     json: boolean;
 }): Command;
-export {};

package/dist/commands/fetch.js

@@ -1,29 +1,8 @@
-import { Command, InvalidArgumentError } from 'commander';
+import { Command } from 'commander';
 import { buildClient } from '../client.js';
 import { printResult, emitFetchResult, handleError } from '../output.js';
 import { parseBulkLines } from '../lib/url-lines.js';
-import { parseIntFlag, parseEnum, parseCacheTtl, parseJsonFlag } from '../lib/parse-flags.js';
-const FETCH_FORMATS = ['markdown', 'html'];
-/** The `FetchRequest.markdown_mode` spec enum (create/POST only — excluded from the GET query). */
-const MARKDOWN_MODES = ['article', 'raw', 'llm'];
-/** The `markdown_links` / `markdown_images` render-mode enum (shared with `scrape create`). */
-const MARKDOWN_RENDER_MODES = ['inline', 'references', 'none', 'text'];
-/**
- * Validate `--format` locally, before any HTTP request is issued.
- *
- * The SDK's `FetchOpts.format` is narrowed to the spec union `'markdown' | 'html'`
- * (#2475), so an off-spec value like `pdf` is a compile-time error at the call site.
- * Commander runs an option's argParser during parsing — ahead of the action callback —
- * so rejecting here means the client is never built and no request is issued, and the
- * caller gets an actionable message instead of a server 422 (same convention as
- * `parseLimit` in search.ts).
- */
-export function parseFormat(value) {
-    if (!FETCH_FORMATS.includes(value)) {
-        throw new InvalidArgumentError(`--format must be one of: ${FETCH_FORMATS.join(', ')}.`);
-    }
-    return value;
-}
+import { parseIntFlag, parseCacheTtl, parseJsonFlag } from '../lib/parse-flags.js';
 export function makeFetchCommand(getGlobal) {
     const cmd = new Command('fetch').description('Fetch URL content operations');
     const bulkCmd = new Command('bulk').description('Bulk fetch operations');
@@ -82,23 +61,9 @@ export function makeFetchCommand(getGlobal) {
         .command('create')
         .description('Fetch URL content (POST)')
         .requiredOption('--url <url>', 'URL to fetch')
-        .option('--format <format>', 'Response format (markdown or html)', parseFormat)
         .option('--country <cc>', 'Two-letter country code to route the request through (e.g. us, de)')
         .option('--timeout-ms <n>', 'Per-request timeout in milliseconds', (v) => parseIntFlag('--timeout-ms', v))
         .option('--cache-ttl <ttl>', 'Cache freshness: 0, Nh (hours), or Nd (days), e.g. 48h, 2d, 0 (omitted → server default)', (v) => parseCacheTtl('--cache-ttl', v))
-        // The markdown surface below is POST-only: FetchGetOpts excludes it, so adding any of it to
-        // `get` would be a compile error — the create/get asymmetry is correct by construction.
-        .option('--markdown-mode <mode>', `Markdown mode: ${MARKDOWN_MODES.join(', ')}`, (v) => parseEnum('--markdown-mode', MARKDOWN_MODES, v))
-        .option('--markdown-query <q>', 'BM25 query string for relevance-ranked markdown filtering (omitted → disabled)')
-        .option('--markdown-links <mode>', `Link rendering: ${MARKDOWN_RENDER_MODES.join(', ')} (omitted → server default)`, (v) => parseEnum('--markdown-links', MARKDOWN_RENDER_MODES, v))
-        .option('--markdown-images <mode>', `Image retention: ${MARKDOWN_RENDER_MODES.join(', ')} (omitted → server default)`, (v) => parseEnum('--markdown-images', MARKDOWN_RENDER_MODES, v))
-        .option('--with-links-summary', 'Append a Links footer to the markdown output (omitted → off)')
-        .option('--with-images-summary', 'Append an Images footer to the markdown output (omitted → off)')
-        .option('--markdown-compact', 'Collapse excessive whitespace in the markdown output (omitted → off)')
-        .option('--markdown-filter-images', 'Filter low-signal images from the markdown output (omitted → off)')
-        .option('--markdown-include-media', 'Return rich link/image objects and a tables array (omitted → off)')
-        .option('--markdown-include-warnings', 'Include markdown-pipeline and tag-filter warnings (omitted → off)')
-        .option('--markdown-include-stats', 'Include a top-level stats object (chars, tokens, blocks) (omitted → off)')
         .option('--custom <json>', `User payload echoed on the envelope as a JSON object, e.g. '{"job":"1"}' (omitted → none)`, (v) => parseJsonFlag('--custom', v, 'object'))
         .option('-o, --output <file>', 'Write the fetched body bytes to the given file path')
         .action(async (opts) => {
@@ -108,36 +73,12 @@ export function makeFetchCommand(getGlobal) {
         // exact same wire output they had as inline spreads; a boolean is written ONLY on
         // `=== true`, so it never serializes `false` (#2480 E1).
         const body = { url: opts.url };
-        if (opts.format !== undefined)
-            body['format'] = opts.format;
         if (opts.country !== undefined)
             body['country'] = opts.country;
         if (opts.timeoutMs !== undefined)
             body['timeout_ms'] = opts.timeoutMs;
         if (opts.cacheTtl !== undefined)
             body['cache_ttl'] = opts.cacheTtl;
-        if (opts.markdownMode !== undefined)
-            body['markdown_mode'] = opts.markdownMode;
-        if (opts.markdownQuery !== undefined)
-            body['markdown_query'] = opts.markdownQuery;
-        if (opts.markdownLinks !== undefined)
-            body['markdown_links'] = opts.markdownLinks;
-        if (opts.markdownImages !== undefined)
-            body['markdown_images'] = opts.markdownImages;
-        if (opts.withLinksSummary === true)
-            body['with_links_summary'] = true;
-        if (opts.withImagesSummary === true)
-            body['with_images_summary'] = true;
-        if (opts.markdownCompact === true)
-            body['markdown_compact'] = true;
-        if (opts.markdownFilterImages === true)
-            body['markdown_filter_images'] = true;
-        if (opts.markdownIncludeMedia === true)
-            body['markdown_include_media'] = true;
-        if (opts.markdownIncludeWarnings === true)
-            body['markdown_include_warnings'] = true;
-        if (opts.markdownIncludeStats === true)
-            body['markdown_include_stats'] = true;
         if (opts.custom !== undefined)
             body['custom'] = opts.custom;
         try {
@@ -154,7 +95,6 @@ export function makeFetchCommand(getGlobal) {
         .command('get')
         .description('Fetch URL content (GET via query params)')
         .requiredOption('--url <url>', 'URL to fetch')
-        .option('--format <format>', 'Response format (markdown or html)', parseFormat)
         .option('--country <cc>', 'Two-letter country code to route the request through (e.g. us, de)')
         .option('--timeout-ms <n>', 'Per-request timeout in milliseconds', (v) => parseIntFlag('--timeout-ms', v))
         .option('--cache-ttl <ttl>', 'Cache freshness: 0, Nh (hours), or Nd (days), e.g. 48h, 2d, 0 (omitted → server default)', (v) => parseCacheTtl('--cache-ttl', v))
@@ -166,7 +106,6 @@ export function makeFetchCommand(getGlobal) {
             const client = buildClient(g);
             const result = await client.fetch.get({
                 url: opts.url,
-                ...(opts.format !== undefined ? { format: opts.format } : {}),
                 ...(opts.country !== undefined ? { country: opts.country } : {}),
                 ...(opts.timeoutMs !== undefined ? { timeout_ms: opts.timeoutMs } : {}),
                 ...(opts.cacheTtl !== undefined ? { cache_ttl: opts.cacheTtl } : {}),

package/dist/commands/scrape.js

@@ -48,7 +48,7 @@ export function makeScrapeCommand(getGlobal) {
         .requiredOption('--file <path>', 'Path to a newline-delimited file. Each line is a plain URL, or a JSON object carrying "url" plus per-item config. A line whose only key is "url" behaves exactly as before (sent as a bare URL string); any line with additional keys switches the payload to the per-item shape.')
         .requiredOption('--webhook-url <url>', 'HTTPS webhook URL notified when the job completes')
         .option('--webhook-secret <secret>', 'HMAC secret used to sign the completion webhook (omitted → unsigned)')
-        .option('--defaults <json>', 'Defaults applied to every entry, as a JSON object (omitted → none). Unknown keys are rejected by /v1/bulk (422) and ignored by scrape bulk / fetch bulk; fetch bulk additionally rejects browser-only keys (cookies, wait_until, wait_for_selector, delay_ms) with a 400.', (v) => parseJsonFlag('--defaults', v, 'object'))
+        .option('--defaults <json>', 'Defaults applied to every entry, as a JSON object (omitted → none). Unknown keys are rejected by /v1/bulk (422) and ignored by scrape bulk / fetch bulk; fetch bulk additionally rejects browser-only keys (wait_until, wait_for_selector, delay_ms) with a 400. `cookies` and `headers` are no longer accepted by any capture endpoint and 400 (#3242).', (v) => parseJsonFlag('--defaults', 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'))
         // /v1/scrape/bulk is the ONE bulk endpoint with a top-level `custom`
         // (validators/scrape-bulk.ts:88). Per-entry `custom` arrives through --file lines instead.
@@ -115,8 +115,6 @@ export function makeScrapeCommand(getGlobal) {
         .option('--markdown-mode <mode>', `Markdown extraction mode: ${MARKDOWN_MODES.join(', ')}`, (v) => parseEnum('--markdown-mode', MARKDOWN_MODES, v))
         .option('--markdown-query <q>', 'BM25 query string for relevance-ranked markdown filtering (omitted → disabled)')
         .option('--cache-ttl <ttl>', 'Cache freshness: 0, Nh (hours), or Nd (days), e.g. 48h, 2d, 0 (omitted → server default)', (v) => parseCacheTtl('--cache-ttl', v))
-        .option('--cookies <json>', `Cookies as a JSON array, e.g. '[{"name":"a","value":"b"}]' (omitted → none)`, (v) => parseJsonFlag('--cookies', v, 'array'))
-        .option('--headers <json>', `Extra request headers as a JSON object, e.g. '{"X-A":"b"}' (omitted → none)`, (v) => parseJsonFlag('--headers', v, 'object'))
         .option('--delay-ms <n>', 'Post-load delay in milliseconds before capture', (v) => parseIntFlag('--delay-ms', v))
         .option('--events <csv>', `Webhook events (comma-separated): ${SCRAPE_EVENTS.join(', ')} (omitted → server default)`, (v) => parseCsv(v).map((e) => parseEnum('--events', SCRAPE_EVENTS, e)))
         .option('--token-encoding <enc>', `Tokenizer for --token-budget: ${TOKEN_ENCODINGS.join(', ')} (omitted → server default)`, (v) => parseEnum('--token-encoding', TOKEN_ENCODINGS, v))
@@ -164,10 +162,6 @@ export function makeScrapeCommand(getGlobal) {
             body['markdown_query'] = opts.markdownQuery;
         if (opts.cacheTtl !== undefined)
             body['cache_ttl'] = opts.cacheTtl;
-        if (opts.cookies !== undefined)
-            body['cookies'] = opts.cookies;
-        if (opts.headers !== undefined)
-            body['headers'] = opts.headers;
         if (opts.delayMs !== undefined)
             body['delay_ms'] = opts.delayMs;
         if (opts.events !== undefined)

package/dist/commands/screenshots.d.ts

@@ -12,6 +12,32 @@ export declare function parseClip(value: string): {
     width: number;
     height: number;
 };
+/**
+ * The advisory note for a `-o` destination whose extension contradicts the captured format, or
+ * undefined when there is nothing to say (#2956 item 3).
+ *
+ * THE DEFECT: `--format` is omitted far more often than not, and the server default is **jpeg** —
+ * so `screenshots create --url … -o shot.png` wrote JPEG bytes into a `.png`-named file, silently,
+ * at exit 0. The mislabelled file then propagated to whatever consumed it next. `screenshots get`
+ * has no `--format` flag at all, so it could not even be told what it was downloading.
+ *
+ * ADVISORY, NOT ENFORCEMENT — this returns a message; the caller writes it to STDERR and proceeds.
+ * The bytes on disk and the exit code are untouched, because the caller may well have meant it
+ * (`-o` is also how you rename an artifact), and because refusing the write would throw away a
+ * capture that was already taken and billed. It stays on the `-o` write path rather than moving
+ * into `downloadArtifact`: that helper is format-agnostic and has no business knowing about image
+ * extensions.
+ *
+ * Silent unless BOTH sides name a recognized image format AND they differ. Nothing to compare —
+ * `-o -` (stdout, no filename to mislabel), an extension-less or non-image destination, an
+ * artifact URL with no usable extension — means no note, never a guessed one.
+ *
+ * `-o -` needs no special case of its own: the literal `-` carries no extension, so
+ * {@link formatFromPath} already returns undefined for it. An explicit early return was written
+ * first and then removed — no mutation of it could turn a test red, which is the definition of a
+ * line that guards nothing. The stdout case stays PINNED by a test either way.
+ */
+export declare function formatMismatchNote(imageUrl: string, dest: string): string | undefined;
 export declare function makeScreenshotsCommand(getGlobal: () => GlobalOptions & {
     json: boolean;
 }): Command;

package/dist/commands/screenshots.js

@@ -99,6 +99,91 @@ function notReadyScreenshot(result) {
         return undefined;
     return { id: obj.id, status };
 }
+/**
+ * Image extensions this CLI recognizes, mapped to their canonical format name.
+ *
+ * `jpg` and `jpeg` are the SAME format under two spellings — collapsing them here is what keeps
+ * the note off `-o shot.jpg`, which is the commonest spelling of a perfectly correct destination.
+ * The set is deliberately small: it exists to decide whether a name makes a FORMAT CLAIM at all,
+ * and an extension outside it (`.bin`, `.tmp`, none) makes none.
+ */
+const IMAGE_EXTENSIONS = {
+    jpg: 'jpeg',
+    jpeg: 'jpeg',
+    png: 'png',
+};
+/**
+ * The canonical image format named by a path's extension, or undefined when it names none.
+ *
+ * Reads the extension off the last path SEGMENT so a directory containing a dot cannot supply one,
+ * and requires a non-empty stem so a dotfile (`.png`) is a name, not an extension.
+ */
+function formatFromPath(path) {
+    const segment = path.slice(path.lastIndexOf('/') + 1);
+    const dot = segment.lastIndexOf('.');
+    if (dot <= 0)
+        return undefined;
+    return IMAGE_EXTENSIONS[segment.slice(dot + 1).toLowerCase()];
+}
+/**
+ * The format the artifact was actually captured in, read off its `image_url`, or undefined.
+ *
+ * `screenshotKey` (`packages/worker/src/storage/b2.ts:60`) builds the object key as
+ * `screenshots/<account>/<date>/<screenshot_id>.<format>`, so the URL's PATHNAME extension is the
+ * captured format — the only place the CLI can observe it. `ScreenshotResponse`
+ * (`docs/api/openapi.yaml`) carries no `format` field, and `screenshots get` has no `--format`
+ * flag, so neither the envelope nor the argv can answer this on the poll path.
+ *
+ * The pathname — never the raw string. A completed `image_url` is an AWS SigV4 PRESIGNED URL
+ * (`?X-Amz-Credential=…&X-Amz-Signature=…`, `gateway/src/lib/signed-url.ts`), and a
+ * `lastIndexOf('.')` over the whole string reads the signature instead of the key. An unparseable
+ * URL yields undefined rather than throwing: this is advisory, and it runs immediately before a
+ * download that must not be blocked by it.
+ */
+function capturedFormat(imageUrl) {
+    try {
+        return formatFromPath(new URL(imageUrl).pathname);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The advisory note for a `-o` destination whose extension contradicts the captured format, or
+ * undefined when there is nothing to say (#2956 item 3).
+ *
+ * THE DEFECT: `--format` is omitted far more often than not, and the server default is **jpeg** —
+ * so `screenshots create --url … -o shot.png` wrote JPEG bytes into a `.png`-named file, silently,
+ * at exit 0. The mislabelled file then propagated to whatever consumed it next. `screenshots get`
+ * has no `--format` flag at all, so it could not even be told what it was downloading.
+ *
+ * ADVISORY, NOT ENFORCEMENT — this returns a message; the caller writes it to STDERR and proceeds.
+ * The bytes on disk and the exit code are untouched, because the caller may well have meant it
+ * (`-o` is also how you rename an artifact), and because refusing the write would throw away a
+ * capture that was already taken and billed. It stays on the `-o` write path rather than moving
+ * into `downloadArtifact`: that helper is format-agnostic and has no business knowing about image
+ * extensions.
+ *
+ * Silent unless BOTH sides name a recognized image format AND they differ. Nothing to compare —
+ * `-o -` (stdout, no filename to mislabel), an extension-less or non-image destination, an
+ * artifact URL with no usable extension — means no note, never a guessed one.
+ *
+ * `-o -` needs no special case of its own: the literal `-` carries no extension, so
+ * {@link formatFromPath} already returns undefined for it. An explicit early return was written
+ * first and then removed — no mutation of it could turn a test red, which is the definition of a
+ * line that guards nothing. The stdout case stays PINNED by a test either way.
+ */
+export function formatMismatchNote(imageUrl, dest) {
+    const requested = formatFromPath(dest);
+    if (requested === undefined)
+        return undefined;
+    const actual = capturedFormat(imageUrl);
+    if (actual === undefined || actual === requested)
+        return undefined;
+    const ext = dest.slice(dest.lastIndexOf('.'));
+    return (`Note: the screenshot was captured as ${actual}, but ${dest} names ${ext}. ` +
+        `The file holds ${actual} bytes — pass --format ${requested} to capture it as ${requested}.`);
+}
 /**
  * The failure carried by the FLAT `error_code`/`error_message` fields, or undefined (#2792).
  *
@@ -220,7 +305,15 @@ async function emitScreenshot(result, opts) {
             process.exitCode = QUEUED_EXIT_CODE;
             return;
         }
-        await downloadArtifact(extractImageUrl(result), opts.output);
+        const imageUrl = extractImageUrl(result);
+        // Advisory only — see {@link formatMismatchNote}. Emitted BEFORE the download so the note is
+        // never lost to a failing fetch, and to STDERR so `-o -` pipelines and stdout redirects stay
+        // byte-identical. It is deliberately unreachable from the not-ready branch above (no artifact
+        // exists, so there is no format to compare) and from `extractImageUrl`'s throw paths.
+        const note = formatMismatchNote(imageUrl, opts.output);
+        if (note !== undefined)
+            console.error(note);
+        await downloadArtifact(imageUrl, opts.output);
         return;
     }
     printResult(result, opts.json);
@@ -253,8 +346,6 @@ 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.')
@@ -301,12 +392,8 @@ 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;
+        // The server defaults metadata to {}; writing an empty container on a bare
+        // create would materialize that default (#2480 E1).
         if (opts.metadata !== undefined)
             body['metadata'] = opts.metadata;
         try {

package/dist/commands/search.js

@@ -6,8 +6,33 @@ import { printResult, handleError } from '../output.js';
  *
  * The CLI never surfaces provider-specific fields — only the ranked result
  * columns the API returns.
+ *
+ * GUARD (#2956 item 1): `response.results` is typed as required, but the type describes what the
+ * API PROMISES, not what a given 200 actually carried — a proxy, a stub server, or a future
+ * envelope change can all answer `200 {"ok":true}`. Two distinct defects came out of trusting the
+ * type here:
+ *
+ * - a MISSING (or null) `results` drove the `for…of` below into
+ *   `TypeError: response.results is not iterable`, which reached stderr as the CLI's whole
+ *   diagnostic. It named an internal expression instead of the field, and left the caller with no
+ *   next move;
+ * - a `results` that is a STRING is iterable, so it did not throw at all — it printed one garbled
+ *   row per CHARACTER and exited 0, which is the quieter of the two failures.
+ *
+ * `Array.isArray` is therefore the gate (not a truthiness or length test), and it is checked
+ * BEFORE any row is written so a malformed body can never produce a half-rendered table. An EMPTY
+ * array stays a successful zero-hit search: it prints nothing and exits 0.
+ *
+ * The thrown error is a plain `Error` raised inside the action's `try`, so it reaches
+ * `handleError` — one `Error: `-prefixed stderr line, exit 1, no stack trace — exactly like every
+ * other command's unexpected-body diagnostic. It points at `--json`, which bypasses this renderer
+ * entirely and dumps the raw body, because inspecting that body is the caller's actual next step.
  */
 function renderTable(response) {
+    if (!Array.isArray(response.results)) {
+        throw new Error('search: the response carries no "results" array — the server returned an unexpected 200 body. ' +
+            'Re-run with --json to inspect it.');
+    }
     for (const result of response.results) {
         console.log(`${result.position}. ${result.title}`);
         console.log(`   ${result.url}`);

package/dist/lib/parse-flags.d.ts

@@ -31,7 +31,7 @@ export declare function parseNumberFlag(flag: string, value: string): number;
 export declare function parseCacheTtl(flag: string, value: string): string;
 /**
  * Parse a JSON-object- or JSON-array-valued flag (#2545). The ONLY `JSON.parse` call site for CLI
- * flag values — every JSON-shaped flag (`--cookies`, `--headers`, `--custom`,
+ * flag values — every JSON-shaped flag (`--custom`, `--metadata`, `--defaults`,
  * `--webhook-headers`, `--options`, `--scrape-options`) routes through here, so command modules
  * carry no raw `JSON.parse` (grep-gated). Rejects malformed JSON AND a value whose top-level shape
  * does not match `expect`, with a copy-pasteable example in the message (E5).

package/dist/lib/parse-flags.js

@@ -57,7 +57,7 @@ export function parseCacheTtl(flag, value) {
 }
 /**
  * Parse a JSON-object- or JSON-array-valued flag (#2545). The ONLY `JSON.parse` call site for CLI
- * flag values — every JSON-shaped flag (`--cookies`, `--headers`, `--custom`,
+ * flag values — every JSON-shaped flag (`--custom`, `--metadata`, `--defaults`,
  * `--webhook-headers`, `--options`, `--scrape-options`) routes through here, so command modules
  * carry no raw `JSON.parse` (grep-gated). Rejects malformed JSON AND a value whose top-level shape
  * does not match `expect`, with a copy-pasteable example in the message (E5).

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

@@ -30,12 +30,12 @@ export type BulkLine = string | Record<string, unknown>;
  *
  * 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).
+ * NAMES only — never the raw line or any value. A `--file` line is where auth-bearing per-item
+ * `metadata` lives (#2596; per-item `cookies`/`headers` were removed in #3242), 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[];
 /**

package/dist/lib/url-lines.js

@@ -24,12 +24,12 @@ import { InvalidArgumentError } from 'commander';
  *
  * 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).
+ * NAMES only — never the raw line or any value. A `--file` line is where auth-bearing per-item
+ * `metadata` lives (#2596; per-item `cookies`/`headers` were removed in #3242), 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 function parseBulkLines(file) {
     return readFileSync(file, 'utf8')

package/dist/test-helpers/build-scratch.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Build a scratch COPY of packages/cli (issue #3270), mirroring
+ * `packages/sdk-typescript/src/test-helpers/build-scratch.ts` (issue #2423 cr-2).
+ *
+ * `entrypoint.test.ts` and `queued-raw-flush.test.ts` both need a built `dist/index.js` and both
+ * used to rebuild the shared, workspace `packages/cli/dist` in place whenever it was missing —
+ * racing each other's build under vitest's default parallel file execution on a checkout with no
+ * prior `pnpm build` (one file's `existsSync` check passes while the other's build is still
+ * writing `dist/`).
+ *
+ * So instead: copy the tracked, on-disk source (never `dist/`, `tsconfig.tsbuildinfo`, or
+ * `node_modules` — those are the mutable/heavy bits) into a scratch tree that mirrors the real
+ * repo's relative layout (`<scratch>/tsconfig.base.json`, `<scratch>/packages/cli/**`), symlink in
+ * the real `node_modules` (read-only from the child process's point of view — nothing here writes
+ * back into it), and let the caller run the package's own `npm run build` / `npm pack` scripts
+ * against that copy. The real `packages/cli/dist` is never read and never written by either suite.
+ *
+ * @param pkgRoot packages/cli (the real, workspace-shared package root)
+ * @param repoRoot the monorepo root (for tsconfig.base.json, which the scratch tsconfig extends)
+ * @param scratchRoot a fresh tmp dir (e.g. from mkdtempSync) to build the scratch tree under
+ * @returns the scratch package dir (`<scratchRoot>/packages/cli`)
+ */
+export declare function createBuildScratch(pkgRoot: string, repoRoot: string, scratchRoot: string): string;

package/dist/test-helpers/build-scratch.js

@@ -0,0 +1,41 @@
+// Test-only fixture, compiled like any other `src` file (not excluded from the tsc build) — same
+// tradeoff sdk-typescript's own copy of this helper documents: a small compiled fixture lands in
+// `dist/test-helpers/`, but excluding it breaks ESLint's typed-lint project-service resolution.
+import { mkdirSync, cpSync, copyFileSync, symlinkSync } from 'node:fs';
+import { basename, join } from 'node:path';
+/**
+ * Build a scratch COPY of packages/cli (issue #3270), mirroring
+ * `packages/sdk-typescript/src/test-helpers/build-scratch.ts` (issue #2423 cr-2).
+ *
+ * `entrypoint.test.ts` and `queued-raw-flush.test.ts` both need a built `dist/index.js` and both
+ * used to rebuild the shared, workspace `packages/cli/dist` in place whenever it was missing —
+ * racing each other's build under vitest's default parallel file execution on a checkout with no
+ * prior `pnpm build` (one file's `existsSync` check passes while the other's build is still
+ * writing `dist/`).
+ *
+ * So instead: copy the tracked, on-disk source (never `dist/`, `tsconfig.tsbuildinfo`, or
+ * `node_modules` — those are the mutable/heavy bits) into a scratch tree that mirrors the real
+ * repo's relative layout (`<scratch>/tsconfig.base.json`, `<scratch>/packages/cli/**`), symlink in
+ * the real `node_modules` (read-only from the child process's point of view — nothing here writes
+ * back into it), and let the caller run the package's own `npm run build` / `npm pack` scripts
+ * against that copy. The real `packages/cli/dist` is never read and never written by either suite.
+ *
+ * @param pkgRoot packages/cli (the real, workspace-shared package root)
+ * @param repoRoot the monorepo root (for tsconfig.base.json, which the scratch tsconfig extends)
+ * @param scratchRoot a fresh tmp dir (e.g. from mkdtempSync) to build the scratch tree under
+ * @returns the scratch package dir (`<scratchRoot>/packages/cli`)
+ */
+export function createBuildScratch(pkgRoot, repoRoot, scratchRoot) {
+    const pkgDest = join(scratchRoot, 'packages/cli');
+    mkdirSync(join(scratchRoot, 'packages'), { recursive: true });
+    copyFileSync(join(repoRoot, 'tsconfig.base.json'), join(scratchRoot, 'tsconfig.base.json'));
+    cpSync(pkgRoot, pkgDest, {
+        recursive: true,
+        filter: (src) => {
+            const name = basename(src);
+            return name !== 'node_modules' && name !== 'dist' && name !== 'tsconfig.tsbuildinfo';
+        },
+    });
+    symlinkSync(join(pkgRoot, 'node_modules'), join(pkgDest, 'node_modules'), 'dir');
+    return pkgDest;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hunt-labs/bytekit-cli",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "ByteKit CLI — wraps @hunt-labs/bytekit-sdk as shell subcommands",
   "license": "MIT",
   "type": "module",
@@ -41,7 +41,7 @@
   ],
   "dependencies": {
     "commander": "^12.0.0",
-    "@hunt-labs/bytekit-sdk": "^0.7.0"
+    "@hunt-labs/bytekit-sdk": "^0.9.0"
   },
   "scripts": {
     "build": "rm -rf dist tsconfig.tsbuildinfo && tsc",