@openclaw/proxyline 0.2.0 → 0.3.1

package/docs/proxy-tls.md

@@ -0,0 +1,66 @@
+# Proxy TLS
+
+`proxyTls` scopes CA trust **for the proxy endpoint only**. It does not loosen TLS for the destination, and it does not affect Node's default trust store.
+
+## Why scope CA trust
+
+Corporate proxies often present TLS certificates signed by a private CA. Two common approaches that Proxyline avoids:
+
+- Setting `NODE_EXTRA_CA_CERTS` — process-wide trust change, affects every TLS handshake, easy to forget.
+- Setting `NODE_TLS_REJECT_UNAUTHORIZED=0` — disables verification entirely, destroys security.
+
+Proxyline instead supplies a `ca` value **only** to the agent that talks to the proxy. Destination handshakes continue using the system trust store and the caller's `ca` / `rejectUnauthorized` settings.
+
+## Options
+
+```ts
+type ProxylineTlsOptions = Readonly<{
+  ca?: string;     // PEM contents
+  caFile?: string; // path; read with fs.readFileSync(path, "utf8")
+}>;
+```
+
+Pass exactly one. `ca` wins when both are provided. The resolved PEM is forwarded to:
+
+- The internal Proxyline Node agent used for `node:http` and `node:https`.
+- Proxyline's managed undici dispatcher or ambient dispatcher.
+- The `tls.connect` call inside `openProxyConnectTunnel` when the proxy URL is `https://`.
+
+## Recipes
+
+### From disk
+
+```ts
+installGlobalProxy({
+  mode: "managed",
+  proxyUrl: "https://proxy.corp.example:8443",
+  proxyTls: { caFile: "/etc/proxy-ca.pem" },
+});
+```
+
+### Inline PEM
+
+```ts
+import { readFileSync } from "node:fs";
+
+const ca = readFileSync("/etc/proxy-ca.pem", "utf8");
+
+installGlobalProxy({
+  mode: "managed",
+  proxyUrl: "https://proxy.corp.example:8443",
+  proxyTls: { ca },
+});
+```
+
+### Pre-resolving for your own code
+
+```ts
+import { resolveProxyTlsCa } from "@openclaw/proxyline";
+
+const ca = resolveProxyTlsCa({ caFile: "/etc/proxy-ca.pem" });
+// ca is a PEM string, or undefined if no options were supplied
+```
+
+## Destination TLS
+
+Destination TLS is independent of `proxyTls`. When you call `https.request(url, { ca, rejectUnauthorized, ... })`, those options apply to the destination handshake exactly as Node would normally apply them. Proxyline only lifts them off a caller-supplied `agent` so they survive the agent replacement; see [Surfaces — TLS identity preservation](./surfaces.md#tls-identity-preservation).

package/docs/security.md

@@ -0,0 +1,83 @@
+# Security
+
+Proxyline is a Node-process runtime, not an operating-system sandbox. Understanding what it does — and what it cannot do — is essential before relying on it as a policy.
+
+## Assurance model
+
+Proxyline's runtime assurances assume it is installed before application and plugin networking code is loaded. Install it as the first import in the process when proxy routing is part of the security posture.
+
+These assurances apply to the surfaces Proxyline patches or helpers it creates. They do not apply to code that captured networking functions before installation, raw sockets, native transports, or separate bundled transport stacks.
+
+## What Proxyline enforces
+
+In **managed** mode, Proxyline forces traffic through the configured proxy on the surfaces it covers:
+
+- `http.request` / `http.get` / `http.globalAgent`
+- `https.request` / `https.get` / `https.globalAgent`
+- The undici global dispatcher (i.e. `fetch`)
+- WebSocket clients that accept a Node `agent`, via `proxy.createWebSocketAgent()` or by reusing the patched `http.request` during the upgrade
+- Explicit HTTP CONNECT when callers opt in to `openProxyConnectTunnel`
+
+Caller-supplied `http.Agent` / `https.Agent` instances are replaced per request, and `createConnection` overrides are stripped. TLS-relevant agent options are lifted onto the request so destination TLS still validates correctly.
+
+Managed mode can also accept a `bypassPolicy` callback for explicitly trusted direct-routing exceptions, such as local control-plane endpoints. Treat it as part of your security policy: keep it narrow and log matching URLs with `explain()`.
+
+In **ambient** mode the same surfaces are covered when at least one supported `http://` or `https://` proxy endpoint is set through `HTTP_PROXY`, `HTTPS_PROXY`, or `ALL_PROXY`; unsupported proxy schemes are ignored, and `NO_PROXY` is honored.
+
+## What Proxyline cannot enforce
+
+Anything that does not flow through the patched APIs:
+
+- Direct `net.connect` or `tls.connect` calls. Code that opens raw sockets is not seen by Proxyline.
+- Native modules with private transport stacks (e.g. some database drivers, gRPC C bindings).
+- Libraries that import and call `undici.fetch` directly with their own explicit `Dispatcher`. Proxyline's managed `globalThis.fetch` strips explicit dispatchers, but it cannot rewrite every imported undici function reference.
+- DNS resolution itself. Proxyline tells the proxy a hostname; DNS-based exfiltration via the local resolver is out of scope.
+- Sockets opened **before** `installProxyline` ran. Existing keepalive connections continue to use whatever transport they were created with.
+- Module references captured before `installProxyline` ran. Anything that stored `http.request` in a local variable at import time keeps the un-patched reference.
+- Non-standard internals on native `Request` objects created before `installProxyline` ran. Proxyline can normalize standard Request fields, but runtimes do not expose every internal field consistently.
+
+For a process-wide proxy enforcement policy, combine Proxyline with operating-system level controls (egress firewall rules, network namespaces, seccomp, or a sidecar proxy).
+
+## Install order matters
+
+Install Proxyline as the **first** import in your application entry point. Anything that imports `node:http`, `node:https`, `undici`, or a wrapper library before Proxyline is initialized may have already captured the original method references. The patches still apply to future calls into `http.request` etc., but a stale captured reference will bypass them.
+
+```ts
+// entry.ts
+import { installGlobalProxy } from "@openclaw/proxyline";
+
+installGlobalProxy({ mode: "managed", proxyUrl: process.env.PROXY_URL! });
+
+// only after install:
+await import("./app.js");
+```
+
+## Process-wide singleton
+
+Only one Proxyline runtime can be installed at a time. A second `installProxyline` call throws `ProxylineError` with code `RUNTIME_ALREADY_ACTIVE` by default. Use `ifActive: "reuse-compatible"` to share the current matching runtime, `ifActive: "replace"` to stop and reinstall intentionally, or call `proxy.stop()` yourself before installing a different runtime.
+
+This is deliberate: two competing proxy patches would race on `http.request` and `globalAgent`, and the loser would silently bypass the winner.
+
+## Credential handling
+
+- Userinfo in proxy URLs becomes a `Proxy-Authorization: Basic` header on every CONNECT / absolute-form request.
+- Userinfo, search, and fragment are stripped from any URL Proxyline reports back to the caller (`handle.proxyUrl`, `decision.proxyUrl`, `runtime.installed`).
+- `redactProxyUrl` is exported so callers can apply the same rule to URLs they log themselves.
+
+## Threat model summary
+
+| Threat | Mitigated | Notes |
+| --- | --- | --- |
+| Library passes a direct `http.Agent` per request | yes (managed) | Replaced before the request runs |
+| Library passes a direct `Dispatcher` to managed `globalThis.fetch` | yes | Explicit dispatchers are stripped |
+| Trusted local endpoint needs direct routing | yes, with `bypassPolicy` | Keep the callback narrow and auditable |
+| Library calls imported `undici.fetch` with a direct `Dispatcher` | no | Imported function references are outside the global fetch patch |
+| Library uses `net.connect` directly | no | Out of scope |
+| Library captured `http.request` at import time | no (if before install) | Install Proxyline first |
+| Environment variable set after install | no | Snapshot at install time |
+| Proxy credentials leaked into logs | yes (in Proxyline output) | Use `redactProxyUrl` for caller logs |
+| Process-wide CA trust drift | yes | `proxyTls` is scoped to the proxy endpoint |
+
+## Reporting
+
+Security issues: open a private advisory at <https://github.com/openclaw/proxyline/security/advisories>. Do not open public issues for unpatched problems.

package/docs/surfaces.md

@@ -0,0 +1,116 @@
+# Surfaces
+
+Proxyline installs at the layer above each network API. It does not own sockets, except via the explicit `openProxyConnectTunnel` helper.
+
+## node:http and node:https
+
+Both modules have their request entry points patched and their `globalAgent` replaced.
+
+Patched methods:
+
+- `http.request`, `http.get`
+- `https.request`, `https.get`
+
+Per request, Proxyline:
+
+1. Copies the call's options object so caller state is not mutated.
+2. Reads TLS-relevant options off any caller-supplied `agent` and lifts them onto the request options (see [TLS identity preservation](#tls-identity-preservation)).
+3. Sets `servername` to the destination hostname when not already set and the hostname is not an IP literal.
+4. Builds a fresh Proxyline Node agent for the request and assigns it as `options.agent`.
+5. Deletes any `createConnection` override so callers cannot punch through to the kernel directly.
+6. Destroys the per-request proxy agent when the request closes.
+
+This means caller agents are not just ignored — the per-request agent is replaced before the original method runs, so even libraries that read `req.agent` after construction see the proxy agent.
+
+### TLS identity preservation
+
+When the caller supplied an `https.Agent` with TLS options, the following keys are lifted into the request so the destination TLS handshake still validates correctly:
+
+`ca`, `cert`, `ciphers`, `clientCertEngine`, `crl`, `dhparam`, `ecdhCurve`, `honorCipherOrder`, `key`, `maxVersion`, `minVersion`, `passphrase`, `pfx`, `rejectUnauthorized`, `secureOptions`, `secureProtocol`, `sessionIdContext`.
+
+The destination `servername` is also inferred from the URL or `hostname`/`host` options when the caller did not set one. IP literals are not used as SNI values.
+
+### Absolute-form requests
+
+Some HTTP clients build absolute-form requests themselves (e.g. `path: "https://api.example.com/graphql"`). Proxyline leaves the path intact and forwards it through the proxy unchanged, so libraries that already implement their own proxy handling continue to function.
+
+## undici and fetch
+
+`installGlobalProxy` calls `undici.setGlobalDispatcher` and patches `globalThis.fetch` to use Proxyline's dispatcher with:
+
+- Proxyline's managed dispatcher in managed mode, backed by `undici.ProxyAgent` instances pointed at `proxyUrl` and trusting `proxyTls` when supplied.
+- Proxyline's ambient dispatcher in ambient mode, resolving each request against the current install-time `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY` snapshot, with the same `proxyTls`.
+
+The original dispatcher and fetch globals are captured and restored on `stop()`.
+Pass `undici` options to tune Proxyline-owned dispatcher defaults such as `bodyTimeout`, `headersTimeout`, `allowH2`, and `connect.autoSelectFamily`.
+
+```ts
+import { fetch } from "undici";
+
+await fetch("https://api.example.com/health"); // routed through Proxyline
+```
+
+In managed mode, Proxyline's patched `globalThis.fetch` ignores explicit `dispatcher` options so a per-call undici `Agent` cannot bypass the managed proxy. In ambient mode, and for callers using imported `undici.fetch` directly, an explicit undici `Agent` or `Dispatcher` still wins. Use `proxy.createUndiciDispatcher()` to get a dispatcher pre-wired to the same policy.
+
+Proxyline also replaces `globalThis.Request`, `Response`, `Headers`, and `FormData` with versions from its undici dependency so `globalThis.fetch` receives compatible objects on Node versions where the built-in fetch no longer shares the package dispatcher. Requests created before Proxyline installs are normalized through the standard public `Request` fields. Install Proxyline first if you need non-standard Request internals, such as a dispatcher embedded in a pre-install native `Request`, to be preserved.
+
+## WebSocket
+
+WebSocket clients that accept a Node `agent` option (e.g. `ws`) can route through the proxy via:
+
+```ts
+import WebSocket from "ws";
+
+const socket = new WebSocket("wss://events.example.com/", {
+  agent: proxy.createWebSocketAgent(),
+});
+```
+
+When ambient mode is inactive, `createWebSocketAgent()` returns a direct-routing agent, so calling code does not need a conditional path.
+
+Clients that do **not** expose an `agent` option but still route their handshake through `http.request` are covered automatically by the global patch.
+
+## HTTP CONNECT tunnel
+
+Some libraries — notably HTTP/2 clients — need ownership of the underlying socket. `openProxyConnectTunnel` performs an `HTTP CONNECT` against the proxy and resolves with a connected `net.Socket` (or `tls.TLSSocket` for HTTPS proxies).
+
+```ts
+import { openProxyConnectTunnel } from "@openclaw/proxyline";
+
+const socket = await openProxyConnectTunnel({
+  proxyUrl: "https://proxy.corp.example:8443",
+  proxyTls: { caFile: "/etc/proxy-ca.pem" },
+  targetHost: "api.example.com",
+  targetPort: 443,
+  timeoutMs: 2_000,
+});
+```
+
+Properties:
+
+- HTTP and HTTPS proxy endpoints supported. Other schemes throw `UNSUPPORTED_PROXY_PROTOCOL`.
+- HTTPS proxies use ALPN `http/1.1`. SNI is the proxy hostname unless that is an IP literal.
+- Userinfo in the `proxyUrl` becomes a `Proxy-Authorization: Basic ...` header.
+- A bounded `16 KiB` header buffer protects against malicious or runaway proxy responses.
+- `timeoutMs` is enforced and emits a `CONNECT_FAILED` error on expiry.
+- Bytes the proxy sends after the response headers are re-injected with `socket.unshift()` so the caller sees the full target stream.
+- Non-2xx status lines, header overrun, premature close, and socket errors are all surfaced as `ProxylineError` with code `CONNECT_FAILED`.
+
+The helper is standalone — it does not require `installGlobalProxy` to have been called.
+
+## Caller-built agents
+
+A `http.Agent` or `https.Agent` you construct yourself is **replaced** in managed mode and **replaced when active** in ambient mode. The replacement happens inside the patched `http.request` / `https.request` call: by the time the underlying request starts, `options.agent` already points at a proxy agent.
+
+This is intentional: a common bypass is `new https.Agent({ keepAlive: true })` passed per-request. Without replacement the proxy is silently skipped.
+
+To get a proxy-aware agent without going through the patched globals, use:
+
+- `proxy.createNodeAgent()` — an `http.Agent` that proxies HTTP and HTTPS requests.
+- `createAmbientNodeProxyAgent()` — a standalone ambient helper that returns an agent only when proxy env applies.
+- `proxy.createUndiciDispatcher()` — an undici `Dispatcher` mirroring the current mode.
+- `proxy.createWebSocketAgent()` — an `http.Agent` suitable for WebSocket upgrades.
+
+Helper-created agents and dispatchers are caller-owned. Destroy or close them when the caller is done.
+
+When the runtime is inactive (ambient mode with no env proxy set), these helpers return direct agents/dispatchers.

package/docs/testing.md

@@ -0,0 +1,78 @@
+# Testing
+
+Proxyline ships with an in-process **proxy lab** used by its end-to-end tests. The lab spins up a target HTTP(S) server and a forward proxy on random ports, then asserts that requests routed through Proxyline reach the proxy with the right shape.
+
+The lab lives in `test/support/proxy-lab.ts`. It is not exported from the package — copy it into your own test suite if you find it useful.
+
+## Run the suite
+
+```bash
+pnpm check       # build + typecheck + coverage-gated tests
+pnpm test        # build + unit, integration, and package-entrypoint tests
+pnpm coverage    # build + tests with native Node source coverage
+pnpm typecheck   # type-only
+```
+
+`pnpm test` builds `dist/`, then runs `node --test` via `tsx` against `test/index.test.ts` (unit), `test/e2e.test.ts` (integration), and `test/package.test.ts` (package entrypoint).
+`pnpm check` enforces native Node coverage for `src/**/*.ts` with thresholds of 85% lines, 80% branches, and 80% functions on Node versions that expose native threshold flags.
+CI runs that check on Ubuntu, macOS, and Windows across Node 20.18.1, 22, 24, and 26; Node 20.18.1 keeps the declared minimum covered with native coverage enabled and skips only the unavailable threshold/include flags.
+
+## What the lab covers
+
+The lab proxy:
+
+- Accepts absolute-form HTTP proxy requests and HTTPS CONNECT tunnels.
+- Denies configured paths (e.g. `/denied` returns `403`).
+- Blocks loopback authorities by default with an explicit allowlist for the lab's own target.
+- Optionally requires a `Proxy-Authorization` header.
+- Optionally runs over HTTPS with a freshly generated CA.
+
+The lab target:
+
+- Serves `/allowed` (`200`) and `/denied` (`200` if reached, which the proxy is supposed to prevent).
+- Optionally runs over HTTPS with a generated certificate scoped to the test host.
+
+Test coverage exercises:
+
+- Absolute-form HTTP proxy requests
+- HTTP CONNECT tunneling
+- Path denial via the proxy
+- Loopback blocking with explicit allowlists
+- HTTPS proxy endpoints with scoped CA trust
+- node:http global routing
+- Caller-supplied agent override (managed mode)
+- Managed-mode `bypassPolicy`
+- HTTPS caller agent TLS option preservation
+- undici/fetch routing
+- WebSocket agent routing
+- Forced upgrade through the patched `http.request`
+- Explicit CONNECT socket routing
+- Ambient `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY` (with credentials), lowercase variants, `NO_PROXY` exemptions, IPv6 bypass entries, bare endpoints
+
+## Writing tests against Proxyline
+
+A minimal pattern:
+
+```ts
+import test from "node:test";
+import assert from "node:assert/strict";
+import { installGlobalProxy } from "@openclaw/proxyline";
+
+test("explain says the proxy is being used", () => {
+  const proxy = installGlobalProxy({
+    mode: "managed",
+    proxyUrl: "http://127.0.0.1:1",
+  });
+  try {
+    const decision = proxy.explain("https://api.example.com/health");
+    assert.equal(decision.kind, "proxied");
+    assert.equal(decision.reason, "managed-proxy-active");
+  } finally {
+    proxy.stop();
+  }
+});
+```
+
+Always call `stop()` in `finally`. The runtime is process-global; a leaked install causes the next test's `installProxyline` to throw `RUNTIME_ALREADY_ACTIVE`.
+
+For ambient-mode tests, scope environment changes with a helper that snapshots and restores `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, `NO_PROXY` (and their lowercase forms). See `test/e2e.test.ts` for the `withProxyEnv` helper used by the suite.

package/docs/troubleshooting.md

@@ -0,0 +1,71 @@
+# Troubleshooting
+
+## `ProxylineError: MANAGED_PROXY_URL_REQUIRED`
+
+You used `mode: "managed"` without `proxyUrl`. Managed mode does not fall back to the environment. Supply a URL or switch to `mode: "ambient"`.
+
+## `ProxylineError: UNSUPPORTED_PROXY_PROTOCOL`
+
+`proxyUrl` is not `http://` or `https://`. SOCKS and other transports are not supported.
+
+## `ProxylineError: RUNTIME_ALREADY_ACTIVE`
+
+Two parts of your code called `installProxyline` without an intervening `stop()` or compatible `ifActive` policy. Find the existing handle and reuse it, pass `ifActive: "reuse-compatible"` when the settings should match, or call `stop()` before the second install. Common causes: test setup that re-installs on every test, double-invoked entry points, hot-reload tooling that re-evaluates the entry module.
+
+## `ProxylineError: CONNECT_FAILED`
+
+Returned by `openProxyConnectTunnel`. Inspect the message for the immediate cause:
+
+- `proxy CONNECT timed out after Nms` — bump `timeoutMs` or check connectivity to the proxy.
+- A status line such as `HTTP/1.1 407 Proxy Authentication Required` — include credentials in `proxyUrl`.
+- A status line such as `HTTP/1.1 403 Forbidden` — the proxy refused the destination.
+- `proxy socket closed before CONNECT response` — the proxy disconnected. Often a TLS mismatch; verify `proxyTls.ca`.
+- `proxy CONNECT response headers exceeded 16384 bytes` — defensive cap. Unexpected from a normal proxy.
+
+## fetch / undici still goes direct
+
+- In ambient mode, a library may be using its own `Dispatcher` and passing it to `fetch` explicitly. Inspect the `dispatcher` option; it overrides the global one outside managed `globalThis.fetch`. Use `proxy.createUndiciDispatcher()` if you need a Proxyline-aware dispatcher.
+- The library was loaded **before** `installProxyline`. Some libraries cache a dispatcher at import time. Install Proxyline first.
+
+## Caller agent is being ignored
+
+That is the intended managed-mode behavior — caller agents are replaced per request. TLS-relevant options (`ca`, `key`, `cert`, `rejectUnauthorized`, `minVersion`, `maxVersion`, `ciphers`, …) are lifted off the caller's agent so destination TLS still validates. If your option is missing, see [Surfaces — TLS identity preservation](./surfaces.md#tls-identity-preservation) for the full list of preserved keys.
+
+## "ECONNREFUSED" against the proxy
+
+Verify the proxy is reachable from this process:
+
+```bash
+curl -v -x "$HTTPS_PROXY" https://api.example.com
+```
+
+If `curl` succeeds but Node fails, the most common causes are:
+
+- Wrong scheme (`HTTPS_PROXY=proxy.corp:8080` defaults to `http://proxy.corp:8080`).
+- A private CA presented by the proxy that Node does not trust. Use `proxyTls`.
+- Code captured `http.request` before Proxyline installed. Install Proxyline first.
+
+## TLS errors against the proxy
+
+The proxy presents a certificate Node does not trust. Pass `proxyTls.caFile` (or `proxyTls.ca`) — see [Proxy TLS](./proxy-tls.md). Do not disable TLS verification process-wide.
+
+## TLS errors against the destination
+
+Proxyline does not modify destination TLS. Use the same `ca` / `cert` / `key` options you would use without a proxy. When passed via an `https.Agent`, Proxyline copies them onto the request automatically.
+
+## Tests interfere with each other
+
+Each test should call `proxy.stop()` in its teardown. Without that, the next install throws `RUNTIME_ALREADY_ACTIVE` and the rest of the suite fails. The patches and the undici dispatcher are global, so leaks affect every concurrent test as well.
+
+## Ambient mode reports `active: false`
+
+No supported proxy variables are set. Check `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY` (and their lowercase forms), and make sure their values use `http://` or `https://`. `NO_PROXY` alone is not enough to activate the runtime. See [Environment Variables](./environment-variables.md).
+
+## `NO_PROXY` is not matching as expected
+
+- Suffix matches need a leading `.` or `*`. `corp.example` matches only the exact host; `.corp.example` matches `api.corp.example`.
+- A port suffix (`internal.corp:8443`) restricts the match to that port.
+- IPv6 hosts may be bracketed or bare (`[::1]`, `::1`).
+- Hostnames are lowercased and trailing dots are stripped before comparison.
+
+When in doubt, use `proxy.explain(url)` — `reason: "no-proxy-match"` confirms the URL was exempted.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/proxyline",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "Process-global proxy routing for Node.js.",
   "type": "module",
   "license": "MIT",
@@ -22,26 +22,37 @@
     ".": {
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
+    },
+    "./dispatcher-brand": {
+      "types": "./dist/dispatcher-brand.d.ts",
+      "default": "./dist/dispatcher-brand.js"
     }
   },
   "files": [
     "dist/*.js",
     "dist/*.d.ts",
     "dist/*.d.ts.map",
+    "src/**/*.ts",
+    "docs/*.md",
+    "docs/CNAME",
+    "scripts/prepack-build.mjs",
+    "tsconfig.json",
+    "tsconfig.build.json",
     "CHANGELOG.md",
     "README.md",
     "LICENSE"
   ],
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
-    "check": "pnpm build && tsc --noEmit && pnpm coverage:run",
+    "check": "pnpm build && tsc --noEmit && pnpm coverage:run && tsx --test test/package-artifact.test.ts",
     "coverage": "pnpm build && pnpm coverage:run",
     "coverage:run": "node scripts/run-coverage.mjs",
     "docs:build": "node scripts/build-docs-site.mjs",
     "package:dry-run": "pnpm pack --dry-run",
     "prepack": "node scripts/prepack-build.mjs",
+    "prepare": "node scripts/prepack-build.mjs",
     "publish:dry-run": "pnpm publish --dry-run --access public",
-    "test": "pnpm build && tsx --test test/index.test.ts test/e2e.test.ts test/package.test.ts",
+    "test": "pnpm build && tsx --test test/index.test.ts test/e2e.test.ts test/package.test.ts test/scripts.test.ts && tsx --test test/package-artifact.test.ts",
     "typecheck": "pnpm build && tsc --noEmit"
   },
   "devDependencies": {
@@ -49,12 +60,13 @@
     "@types/ws": "^8.18.1",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3",
+    "undici": "^7.25.0",
     "ws": "^8.20.0"
   },
   "engines": {
     "node": ">=20.18.1"
   },
-  "dependencies": {
-    "undici": "^7.25.0"
+  "peerDependencies": {
+    "undici": ">=7.25.0 <9"
   }
 }

package/scripts/prepack-build.mjs

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+import { spawnSync } from "node:child_process";
+import { createRequire } from "node:module";
+
+const require = createRequire(import.meta.url);
+
+function resolveTypeScriptCompiler() {
+  try {
+    return require.resolve("typescript/bin/tsc");
+  } catch {
+    return undefined;
+  }
+}
+
+function run(command, args, env = {}) {
+  const result = spawnSync(command, args, {
+    stdio: "inherit",
+    env: { ...process.env, ...env },
+  });
+  if (result.status !== 0) {
+    process.exit(result.status ?? 1);
+  }
+}
+
+const tscBin = resolveTypeScriptCompiler();
+
+if (!tscBin) {
+  console.error("TypeScript compiler is unavailable. Run `pnpm install --frozen-lockfile` before packing.");
+  process.exit(1);
+}
+
+run(process.execPath, [tscBin, "-p", "tsconfig.build.json"]);