[refactor] add Progressive HEAD simulation & Stream utility functions

[Copilot]

HTTPClient.head() previously threw when a server didn't support HEAD. This adds a three-tier fallback chain to simulate HEAD using minimal bandwidth.

Fallback chain

All three tiers use fetch() directly and are encapsulated entirely inside requestHead(), which is called from within the exported request() function:

1. HEAD via fetch() — standard fetch() HEAD request; return on success
2. Range GET — GET with Range: bytes=0-4099 (magic number size per file-type); returns headers (including Content-Range) and the first 4100 bytes as an ArrayBuffer
3. Plain GET via fetch() — reads exactly the first 4100 bytes from the response body using an async generator (for await...of + slice at limit + Array.fromAsync()) then cancels the stream; bytes returned in body

// Servers that reject HEAD and Range will still resolve headers:
const headers = await client.head('https://example.com/file.zip');
// Content-Type, Content-Length, etc. available without downloading the file

Changes

• source/HTTPRequest.ts — requestHead(req) encapsulates the full three-tier chain; all tiers use fetch() directly (no baseRequest parameter); exports FILE_TYPE_MAGIC_NUMBER_SIZE = 4100 constant and HeadResponse interface ({ headers, body?: ArrayBuffer }); the exported request() function wraps rawRequest (XHR/fetch) and for HEAD requests delegates to requestHead(), returning a synthetic Response{status:204}; non-HEAD requests pass through to rawRequest unchanged
• source/utility.ts — exports takeBytes(stream, limit) async generator accepting ReadableStream<Uint8Array> directly; reads chunks via for await...of, yields each (slicing the final chunk to honour the limit exactly), and breaks once limit bytes have been produced; the as unknown cast is internal so callers need no type assertions; exports readBytes(stream, limit) that collects the result via Array.fromAsync() into an ArrayBuffer; used by requestHead() for tier 3
• source/HTTPClient.ts — head() is a plain this.request() wrapper going through the normal middleware chain; HEAD simulation is transparent at the request() layer; defaultWare is a simple throw for status > 299 with no HEAD special case
• test/XMLHttpRequest.ts — simplified mock: dead HEAD→405 special case removed (XHR is no longer called for HEAD)
• test/Request-Client.spec.ts — four tests covering all three fallback tiers and the request() wrapper; Range GET mock includes Content-Range response header; requestHead() calls omit method; expected synthetic status is 204
• test/utility.spec.ts — four tests for takeBytes and readBytes using new Blob([...]).stream() for stream creation (no manual makeStream helper); tests verify exact byte-count behaviour and unlimited collection; no as/unknown/any casts at call sites
• package.json — parcel updated to ^2.16.4 to fix a pre-existing Node.js v24 worker thread crash in the build step

Human changes

1. [add] Readable Stream utility functions (resolve HTTPClient 支持模拟 HEAD 请求 #18)
2. [migrate] upgrade to Node.js 24, PNPM 10, JSDOM 29, Cross Env 10, Lint Staged 16 & other latest Upstream packages/actions
3. [optimize] simplify Copilot codes

---

📍 Connect Copilot coding agent with Jira, Azure Boards or Linear to delegate work to Copilot in one click without leaving your project management tool.

[Copilot]

Just as a heads up, I was blocked by some firewall rules while working on your feedback. Expand below for details.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• jsonplaceholder.typicode.com
  • Triggering command: /home/REDACTED/work/_temp/ghcca-node/node/bin/node node /home/REDACTED/work/KoAJAX/KoAJAX/node_modules/.bin/jest --detectOpenHandles (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)