@hunt-labs/bytekit-cli 0.8.1 → 0.9.0

package/CHANGELOG.md

@@ -10,6 +10,25 @@ 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
@@ -75,6 +94,16 @@ today, see [README.md](./README.md), which remains the authoritative usage guide
   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
@@ -511,8 +540,10 @@ 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`,

package/README.md

@@ -171,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
 ```
@@ -193,30 +193,11 @@ 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 **require** `--url <url>`. Both also accept `--format <format>`
-(`markdown` or `html`), `--country <cc>`, `--timeout-ms <n>`, `--cache-ttl <ttl>`
+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` accepts the full markdown-pipeline surface on top of that, which
-`fetch get` does not:
-
-| Flag                          | Effect                                                                       |
-| ----------------------------- | ---------------------------------------------------------------------------- |
-| `--markdown-mode <mode>`      | Markdown extraction mode: `article`, `raw`, `llm`.                           |
-| `--markdown-query <q>`        | BM25 query for relevance-ranked markdown filtering. Omitted → disabled.      |
-| `--markdown-links <mode>`     | Link rendering: `inline`, `references`, `none`, `text`.                      |
-| `--markdown-images <mode>`    | Image retention: `inline`, `references`, `none`, `text`.                     |
-| `--with-links-summary`        | Append a Links footer to the markdown.                                       |
-| `--with-images-summary`       | Append an Images footer to the markdown.                                     |
-| `--markdown-compact`          | Collapse excessive whitespace.                                               |
-| `--markdown-filter-images`    | Filter low-signal images.                                                    |
-| `--markdown-include-media`    | Return rich link/image objects and a tables array.                           |
-| `--markdown-include-warnings` | Include markdown-pipeline and tag-filter warnings.                           |
-| `--markdown-include-stats`    | Include a top-level stats object (chars, tokens, blocks).                    |
-| `--custom <json>`             | User payload echoed on the envelope, as a JSON object, e.g. `'{"job":"1"}'`. |
-
-Each is omitted when absent, so a server default is never materialized.
+`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).

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.js

@@ -346,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.')
@@ -394,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/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.1",
+  "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.1"
+    "@hunt-labs/bytekit-sdk": "^0.9.0"
   },
   "scripts": {
     "build": "rm -rf dist tsconfig.tsbuildinfo && tsc",