@speedkit/cli 4.23.2 → 4.24.0

package/.env.sample

@@ -20,6 +20,13 @@
 # Chrome Test Browser will use an existing sub-profile named 'Default'
 # within CHROME_USER_PROFILE_PATH or creates one automatically on start up.
 
+# Enforce a SOCKS proxy for every request the CLI sends to a customer origin.
+# The value is a Chrome `--proxy-server` URL, so Chrome and the CLI share one setting.
+# It overrides a `--proxy-server` entry in the customer config's chromeFlags. The CLI then names
+# both proxies, because the customer config pins the exit region its origin expects.
+# Requests to Baqend stay on a direct connection.
+# SK_PROXY_SERVER='socks5://ap-northeast-1.proxy.baqend.com:1080'
+
 # Slack Deploy Token
 # SLACK_TOKEN='<SLACK_TOKEN_FROM_1PASSWORD>'
 

package/CHANGELOG.md

@@ -1,3 +1,24 @@
+# [4.24.0](https://gitlab.orestes.info/baqend/speed-kit-cli/compare/v4.23.3...v4.24.0) (2026-08-28)
+
+
+### Bug Fixes
+
+* **onboarding:** apply the chromeFlags socks proxy to origin requests ([db0ce41](https://gitlab.orestes.info/baqend/speed-kit-cli/commit/db0ce412b3d0a9056d9eb1778da11d6d84649695))
+* **onboarding:** fetch external modules from app ([59646e7](https://gitlab.orestes.info/baqend/speed-kit-cli/commit/59646e744fdeaf1f4b9e0091cc1c0c625478f2ab))
+* **onboarding:** guard the crawler against a config without authentications ([10c75b8](https://gitlab.orestes.info/baqend/speed-kit-cli/commit/10c75b86fd2e7191057d04f2d1b257f7b2c4b577))
+
+
+### Features
+
+* **cli:** enforce a socks proxy for every origin request via SK_PROXY_SERVER ([66fab11](https://gitlab.orestes.info/baqend/speed-kit-cli/commit/66fab119e3a5cb2f040c6d91c5f1f10b19e4e2a8))
+
+## [4.23.3](https://gitlab.orestes.info/baqend/speed-kit-cli/compare/v4.23.2...v4.23.3) (2026-08-25)
+
+
+### Bug Fixes
+
+* **deploy:** match refresh job names by prefix ([c593d9d](https://gitlab.orestes.info/baqend/speed-kit-cli/commit/c593d9d69db8e05ccb71b320cb4f9c7cbda5cdac))
+
 ## [4.23.2](https://gitlab.orestes.info/baqend/speed-kit-cli/compare/v4.23.1...v4.23.2) (2026-08-21)
 
 

package/README.md

@@ -21,7 +21,7 @@ $ npm install -g @speedkit/cli
 $ sk COMMAND
 running command...
 $ sk (--version)
-@speedkit/cli/4.23.2 linux-x64 node-v22.23.2
+@speedkit/cli/4.24.0 linux-x64 node-v22.23.2
 $ sk --help [COMMAND]
 USAGE
   $ sk COMMAND

package/dist/helpers/origin-proxy.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Environment variable that enforces a SOCKS proxy for every origin-directed request the CLI
+ * makes. It carries a Chrome `--proxy-server` value, so one string serves Chrome and the CLI, e.g.
+ * `SK_PROXY_SERVER=socks5://ap-northeast-1.proxy.baqend.com:1080`.
+ */
+export declare const PROXY_ENVIRONMENT_VARIABLE = "SK_PROXY_SERVER";
+/** SOCKS proxy in the shape `socksDispatcher` expects. */
+export interface OriginProxy {
+    type: 4 | 5;
+    host: string;
+    port: number;
+}
+/** Only `writeWarning` is used, so this helper does not depend on the CLI service. */
+export interface ProxyLogger {
+    writeWarning(message: string): void;
+}
+/** Per-request transport choice. */
+export interface OriginFetchOptions {
+    /**
+     * Accepts an untrusted certificate and allows legacy renegotiation. Set it only where the call
+     * site already tolerated a broken origin handshake, because it hides a real certificate fault.
+     */
+    tolerateLegacyTls?: boolean;
+}
+/**
+ * Parses a Chrome `--proxy-server` value into a SOCKS proxy.
+ *
+ * A value without a port takes 1080, the port Chrome assumes for a SOCKS proxy, so one string keeps
+ * working for both.
+ *
+ * @param value - Proxy URL, e.g. `socks5://proxy.example.com:1080`.
+ * @returns The parsed proxy, or undefined when the value is empty or not a SOCKS URL.
+ */
+export declare function parseSocksProxy(value?: string): OriginProxy | undefined;
+/** Renders a proxy as the URL that Chrome and the log lines use. */
+export declare function formatProxy(proxy: OriginProxy): string;
+/** Renders a proxy as the Chrome flag that routes the browser through it. */
+export declare function chromeProxyFlag(proxy: OriginProxy): string;
+/**
+ * Finds the SOCKS proxy that a customer config pins through its Chrome flags.
+ *
+ * @param chromeFlags - `chromeFlags` of the customer config.
+ * @returns The `--proxy-server` value of the first SOCKS entry, or undefined.
+ */
+export declare function findProxyInChromeFlags(chromeFlags?: string[]): string;
+/**
+ * Selects the SOCKS proxy for all origin-directed requests and installs it for `originFetch`.
+ *
+ * `SK_PROXY_SERVER` wins over the customer config, so an operator can route a session through
+ * another region without editing a customer directory. The customer's `--proxy-server` chrome flag
+ * is the fallback.
+ *
+ * A customer pins the proxy for a reason: its origin expects the exit region the config names. The
+ * logger therefore reports both values whenever the environment displaces one, so a forgotten
+ * export cannot silently move a session out of the customer's region.
+ *
+ * @param chromeFlags - `chromeFlags` of the customer config, when a command has one.
+ * @param logger - Receives one line naming the proxy in use.
+ * @returns The proxy in use, or undefined for a direct connection.
+ * @throws When `SK_PROXY_SERVER` holds something that is not a SOCKS URL. Failing is safer than a
+ * silent direct connection, because the operator asked for a proxy.
+ */
+export declare function applyOriginProxy(chromeFlags?: string[], logger?: ProxyLogger): OriginProxy | undefined;
+/**
+ * Installs the proxy that `originFetch` uses. Prefer `applyOriginProxy`. This entry point exists
+ * for tests and for callers that resolved the proxy themselves.
+ */
+export declare function setOriginProxy(proxy?: OriginProxy, fromEnvironment?: boolean): void;
+/** Drops the installed proxy, so the next call resolves it again. */
+export declare function resetOriginProxy(): void;
+/**
+ * Appends the enforced proxy to the Chrome flags of a launch.
+ *
+ * Chrome takes the last `--proxy-server`, so the environment beats a customer config here just as
+ * it does for the CLI. A proxy that came from the flags already is left untouched.
+ *
+ * @param chromeFlags - `chromeFlags` of the customer config.
+ */
+export declare function withOriginProxyFlag(chromeFlags?: string[]): string[];
+/**
+ * Fetches a customer origin through the enforced SOCKS proxy.
+ *
+ * Every request that leaves the CLI for a customer origin has to use this instead of `fetch`, which
+ * carries no proxy support. Requests to Baqend keep their own client and connect directly.
+ *
+ * Node's built-in `fetch` rejects a dispatcher built by the `undici` package, so a request that
+ * needs one runs through undici's own `fetch`. A plain direct request keeps the global `fetch`.
+ */
+export declare function originFetch(url: string, init?: RequestInit, options?: OriginFetchOptions): Promise<Response>;

package/dist/helpers/origin-proxy.js

@@ -0,0 +1,207 @@
+import crypto from "node:crypto";
+import { socksDispatcher } from "fetch-socks";
+import { fetch as undiciFetch } from "undici";
+/**
+ * Environment variable that enforces a SOCKS proxy for every origin-directed request the CLI
+ * makes. It carries a Chrome `--proxy-server` value, so one string serves Chrome and the CLI, e.g.
+ * `SK_PROXY_SERVER=socks5://ap-northeast-1.proxy.baqend.com:1080`.
+ */
+export const PROXY_ENVIRONMENT_VARIABLE = "SK_PROXY_SERVER";
+const PROXY_SCHEMES = {
+    "socks4:": 4,
+    "socks4a:": 4,
+    "socks5:": 5,
+    "socks5h:": 5,
+};
+const CHROME_PROXY_FLAG = "--proxy-server=";
+/** Port Chrome assumes for a SOCKS proxy that names none. */
+const DEFAULT_SOCKS_PORT = 1080;
+let state;
+/**
+ * Parses a Chrome `--proxy-server` value into a SOCKS proxy.
+ *
+ * A value without a port takes 1080, the port Chrome assumes for a SOCKS proxy, so one string keeps
+ * working for both.
+ *
+ * @param value - Proxy URL, e.g. `socks5://proxy.example.com:1080`.
+ * @returns The parsed proxy, or undefined when the value is empty or not a SOCKS URL.
+ */
+export function parseSocksProxy(value) {
+    const trimmed = (value || "").trim();
+    if (!trimmed) {
+        return;
+    }
+    let url;
+    try {
+        url = new URL(trimmed);
+    }
+    catch {
+        return;
+    }
+    const type = PROXY_SCHEMES[url.protocol];
+    if (!type || !url.hostname) {
+        return;
+    }
+    return {
+        type,
+        host: url.hostname,
+        port: url.port ? Number(url.port) : DEFAULT_SOCKS_PORT,
+    };
+}
+/** Renders a proxy as the URL that Chrome and the log lines use. */
+export function formatProxy(proxy) {
+    return `socks${proxy.type}://${proxy.host}:${proxy.port}`;
+}
+/** Renders a proxy as the Chrome flag that routes the browser through it. */
+export function chromeProxyFlag(proxy) {
+    return `${CHROME_PROXY_FLAG}${formatProxy(proxy)}`;
+}
+/**
+ * Finds the SOCKS proxy that a customer config pins through its Chrome flags.
+ *
+ * @param chromeFlags - `chromeFlags` of the customer config.
+ * @returns The `--proxy-server` value of the first SOCKS entry, or undefined.
+ */
+export function findProxyInChromeFlags(chromeFlags = []) {
+    for (const flag of chromeFlags) {
+        if (!flag.startsWith(CHROME_PROXY_FLAG)) {
+            continue;
+        }
+        const value = flag.slice(CHROME_PROXY_FLAG.length);
+        if (parseSocksProxy(value)) {
+            return value;
+        }
+    }
+}
+/**
+ * Selects the SOCKS proxy for all origin-directed requests and installs it for `originFetch`.
+ *
+ * `SK_PROXY_SERVER` wins over the customer config, so an operator can route a session through
+ * another region without editing a customer directory. The customer's `--proxy-server` chrome flag
+ * is the fallback.
+ *
+ * A customer pins the proxy for a reason: its origin expects the exit region the config names. The
+ * logger therefore reports both values whenever the environment displaces one, so a forgotten
+ * export cannot silently move a session out of the customer's region.
+ *
+ * @param chromeFlags - `chromeFlags` of the customer config, when a command has one.
+ * @param logger - Receives one line naming the proxy in use.
+ * @returns The proxy in use, or undefined for a direct connection.
+ * @throws When `SK_PROXY_SERVER` holds something that is not a SOCKS URL. Failing is safer than a
+ * silent direct connection, because the operator asked for a proxy.
+ */
+export function applyOriginProxy(chromeFlags = [], logger) {
+    const fromEnvironment = (process.env[PROXY_ENVIRONMENT_VARIABLE] || "").trim();
+    if (fromEnvironment) {
+        const proxy = parseSocksProxy(fromEnvironment);
+        if (!proxy) {
+            throw new Error(`${PROXY_ENVIRONMENT_VARIABLE}="${fromEnvironment}" is not a SOCKS proxy URL. ` +
+                `Use socks4://host:port or socks5://host:port.`);
+        }
+        setOriginProxy(proxy, true);
+        logger?.writeWarning(enforcedProxyMessage(proxy, chromeFlags));
+        return proxy;
+    }
+    const proxy = parseSocksProxy(findProxyInChromeFlags(chromeFlags));
+    setOriginProxy(proxy, false);
+    if (proxy) {
+        logger?.writeWarning(`use proxy from chromeFlags for every origin request: ${formatProxy(proxy)}`);
+    }
+    return proxy;
+}
+/** True when both proxies name the same SOCKS endpoint. */
+function isSameProxy(one, other) {
+    return (one.type === other.type &&
+        one.host === other.host &&
+        one.port === other.port);
+}
+/**
+ * Builds the line that reports an enforced proxy. A displaced customer proxy is named, because the
+ * operator has to see which region the session left behind.
+ */
+function enforcedProxyMessage(proxy, chromeFlags) {
+    const pinned = parseSocksProxy(findProxyInChromeFlags(chromeFlags));
+    if (pinned && !isSameProxy(pinned, proxy)) {
+        return (`${PROXY_ENVIRONMENT_VARIABLE} replaces the proxy of the customer config. ` +
+            `Chrome and every origin request leave through ${formatProxy(proxy)}, ` +
+            `not through ${formatProxy(pinned)}. Unset the variable to use the customer's region.`);
+    }
+    return `${PROXY_ENVIRONMENT_VARIABLE} routes Chrome and every origin request through ${formatProxy(proxy)}`;
+}
+/**
+ * Installs the proxy that `originFetch` uses. Prefer `applyOriginProxy`. This entry point exists
+ * for tests and for callers that resolved the proxy themselves.
+ */
+export function setOriginProxy(proxy, fromEnvironment = false) {
+    state = { proxy, fromEnvironment };
+}
+/** Drops the installed proxy, so the next call resolves it again. */
+export function resetOriginProxy() {
+    state = undefined;
+}
+/**
+ * Appends the enforced proxy to the Chrome flags of a launch.
+ *
+ * Chrome takes the last `--proxy-server`, so the environment beats a customer config here just as
+ * it does for the CLI. A proxy that came from the flags already is left untouched.
+ *
+ * @param chromeFlags - `chromeFlags` of the customer config.
+ */
+export function withOriginProxyFlag(chromeFlags = []) {
+    const current = currentState();
+    if (!current.proxy || !current.fromEnvironment) {
+        return chromeFlags;
+    }
+    return [...chromeFlags, chromeProxyFlag(current.proxy)];
+}
+/**
+ * Fetches a customer origin through the enforced SOCKS proxy.
+ *
+ * Every request that leaves the CLI for a customer origin has to use this instead of `fetch`, which
+ * carries no proxy support. Requests to Baqend keep their own client and connect directly.
+ *
+ * Node's built-in `fetch` rejects a dispatcher built by the `undici` package, so a request that
+ * needs one runs through undici's own `fetch`. A plain direct request keeps the global `fetch`.
+ */
+export function originFetch(url, init, options = {}) {
+    const dispatcher = originDispatcher(options.tolerateLegacyTls === true);
+    if (!dispatcher) {
+        return fetch(url, init);
+    }
+    const request = { ...init, dispatcher };
+    return undiciFetch(url, request);
+}
+function currentState() {
+    if (!state) {
+        applyOriginProxy();
+    }
+    return state;
+}
+/**
+ * Builds the dispatcher for one transport and caches it.
+ *
+ * `socksDispatcher` connects directly when it gets no proxy, so the same builder serves a tolerant
+ * direct request. A strict direct request needs no dispatcher at all.
+ *
+ * @param tolerateLegacyTls - Accept an untrusted certificate and allow legacy renegotiation.
+ */
+function originDispatcher(tolerateLegacyTls) {
+    const current = currentState();
+    if (!current.proxy && !tolerateLegacyTls) {
+        return;
+    }
+    const proxies = current.proxy ? [current.proxy] : [];
+    const connect = tolerateLegacyTls
+        ? {
+            keepAlive: true,
+            rejectUnauthorized: false,
+            secureOptions: crypto.constants.SSL_OP_LEGACY_SERVER_CONNECT,
+        }
+        : { keepAlive: true };
+    if (tolerateLegacyTls) {
+        current.tolerantDispatcher ??= socksDispatcher(proxies, { connect });
+        return current.tolerantDispatcher;
+    }
+    current.strictDispatcher ??= socksDispatcher(proxies, { connect });
+    return current.strictDispatcher;
+}

package/dist/helpers/origin-proxy.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/helpers/origin-proxy.spec.js

@@ -0,0 +1,167 @@
+import { expect } from "chai";
+import { describe, beforeEach, afterEach, it } from "mocha";
+import http from "node:http";
+import { applyOriginProxy, chromeProxyFlag, findProxyInChromeFlags, originFetch, parseSocksProxy, PROXY_ENVIRONMENT_VARIABLE, resetOriginProxy, setOriginProxy, withOriginProxyFlag, } from "./origin-proxy.js";
+/** Sets or clears the enforcing environment variable. */
+function setEnvironmentProxy(value) {
+    if (value === undefined) {
+        delete process.env.SK_PROXY_SERVER;
+        return;
+    }
+    process.env.SK_PROXY_SERVER = value;
+}
+/** Collects the warnings a caller would print. */
+function recordingLogger() {
+    const warnings = [];
+    return {
+        warnings,
+        writeWarning: (message) => warnings.push(message),
+    };
+}
+describe("origin proxy", () => {
+    const originalEnvironment = process.env.SK_PROXY_SERVER;
+    beforeEach(() => {
+        setEnvironmentProxy(undefined);
+        resetOriginProxy();
+    });
+    afterEach(() => {
+        setEnvironmentProxy(originalEnvironment);
+        resetOriginProxy();
+    });
+    describe("parseSocksProxy", () => {
+        it("keeps the host without the scheme separator", () => {
+            expect(parseSocksProxy("socks5://ap-northeast-1.proxy.baqend.com:1080")).to.deep.equal({
+                type: 5,
+                host: "ap-northeast-1.proxy.baqend.com",
+                port: 1080,
+            });
+        });
+        it("maps every socks scheme to its protocol version", () => {
+            expect(parseSocksProxy("socks4://proxy.example.com:1080").type).to.equal(4);
+            expect(parseSocksProxy("socks4a://proxy.example.com:1080").type).to.equal(4);
+            expect(parseSocksProxy("socks5h://proxy.example.com:1080").type).to.equal(5);
+        });
+        it("takes 1080 for a value without a port, like chrome does", () => {
+            expect(parseSocksProxy("socks5://eu-central-1.proxy.baqend.com")).to.deep.equal({
+                type: 5,
+                host: "eu-central-1.proxy.baqend.com",
+                port: 1080,
+            });
+        });
+        it("rejects a value that is not a socks url", () => {
+            expect(parseSocksProxy("")).to.equal(undefined);
+            expect(parseSocksProxy("http://proxy.example.com:8080")).to.equal(undefined);
+            expect(parseSocksProxy("https://eu-central-1.proxy.baqend.com/")).to.equal(undefined);
+            expect(parseSocksProxy("proxy.example.com:1080")).to.equal(undefined);
+        });
+    });
+    describe("findProxyInChromeFlags", () => {
+        it("finds the socks entry among unrelated flags", () => {
+            const flags = [
+                "--window-size=390,844",
+                "--proxy-server=socks5://proxy.example.com:1080",
+            ];
+            expect(findProxyInChromeFlags(flags)).to.equal("socks5://proxy.example.com:1080");
+        });
+        it("ignores a non-socks proxy flag", () => {
+            expect(findProxyInChromeFlags([
+                "--proxy-server=http://proxy.example.com:8080",
+            ])).to.equal(undefined);
+        });
+        it("survives a config without chrome flags", () => {
+            expect(findProxyInChromeFlags()).to.equal(undefined);
+            expect(findProxyInChromeFlags([])).to.equal(undefined);
+        });
+    });
+    describe("applyOriginProxy", () => {
+        it("takes the proxy from the customer chrome flags", () => {
+            const logger = recordingLogger();
+            const proxy = applyOriginProxy(["--proxy-server=socks5://proxy.example.com:1080"], logger);
+            expect(proxy).to.deep.equal({
+                type: 5,
+                host: "proxy.example.com",
+                port: 1080,
+            });
+            expect(logger.warnings).to.have.length(1);
+        });
+        it("lets the environment override the customer chrome flags", () => {
+            setEnvironmentProxy("socks5://enforced.example.com:1080");
+            const proxy = applyOriginProxy([
+                "--proxy-server=socks5://customer.example.com:1080",
+            ]);
+            expect(proxy.host).to.equal("enforced.example.com");
+        });
+        it("names both proxies when it displaces the customer's region", () => {
+            setEnvironmentProxy("socks5://enforced.example.com:1080");
+            const logger = recordingLogger();
+            applyOriginProxy(["--proxy-server=socks5://ap-northeast-1.proxy.baqend.com:1080"], logger);
+            expect(logger.warnings).to.have.length(1);
+            expect(logger.warnings[0]).to.contain("enforced.example.com");
+            expect(logger.warnings[0]).to.contain("ap-northeast-1.proxy.baqend.com:1080");
+        });
+        it("reports no displacement when both sources name one endpoint", () => {
+            setEnvironmentProxy("socks5h://proxy.example.com:1080");
+            const logger = recordingLogger();
+            applyOriginProxy(["--proxy-server=socks5://proxy.example.com:1080"], logger);
+            expect(logger.warnings[0]).to.not.contain("replaces");
+        });
+        it("fails loudly on an unusable environment value", () => {
+            setEnvironmentProxy("http://proxy.example.com:8080");
+            expect(() => applyOriginProxy()).to.throw(PROXY_ENVIRONMENT_VARIABLE);
+        });
+        it("reports no proxy when neither source sets one", () => {
+            const logger = recordingLogger();
+            expect(applyOriginProxy([], logger)).to.equal(undefined);
+            expect(logger.warnings).to.have.length(0);
+        });
+    });
+    describe("withOriginProxyFlag", () => {
+        it("appends the enforced proxy last, so chrome takes it", () => {
+            setEnvironmentProxy("socks5://enforced.example.com:1080");
+            applyOriginProxy(["--proxy-server=socks5://customer.example.com:1080"]);
+            expect(withOriginProxyFlag([
+                "--proxy-server=socks5://customer.example.com:1080",
+            ])).to.deep.equal([
+                "--proxy-server=socks5://customer.example.com:1080",
+                "--proxy-server=socks5://enforced.example.com:1080",
+            ]);
+        });
+        it("leaves a proxy that already came from the flags untouched", () => {
+            const flags = ["--proxy-server=socks5://customer.example.com:1080"];
+            applyOriginProxy(flags);
+            expect(withOriginProxyFlag(flags)).to.deep.equal(flags);
+        });
+    });
+    describe("chromeProxyFlag", () => {
+        it("round-trips a parsed proxy", () => {
+            const value = "socks5://proxy.example.com:1080";
+            expect(chromeProxyFlag(parseSocksProxy(value))).to.equal(`--proxy-server=${value}`);
+        });
+    });
+    describe("originFetch", () => {
+        let server;
+        let url;
+        beforeEach(async () => {
+            server = http.createServer((_request, response) => response.end("ok"));
+            await new Promise((resolve) => server.listen(0, "127.0.0.1", resolve));
+            url = `http://127.0.0.1:${server.address().port}/`;
+        });
+        afterEach(() => server.close());
+        it("connects directly when no proxy is set", async () => {
+            const response = await originFetch(url);
+            expect(await response.text()).to.equal("ok");
+        });
+        it("connects directly when only legacy tls is tolerated", async () => {
+            const response = await originFetch(url, undefined, {
+                tolerateLegacyTls: true,
+            });
+            expect(await response.text()).to.equal("ok");
+        });
+        it("routes through the installed proxy", async () => {
+            // Nothing listens on port 1, so a proxied request must fail to connect.
+            setOriginProxy({ type: 5, host: "127.0.0.1", port: 1 });
+            const failure = await originFetch(url).then(() => null, (error) => error);
+            expect(failure).to.be.instanceOf(Error);
+        });
+    });
+});

package/dist/helpers/scrape.js

@@ -1,6 +1,6 @@
-import fetch from "node-fetch";
+import { originFetch } from "./origin-proxy.js";
 export default async function scrape(url) {
-    const response = await fetch(url);
+    const response = await originFetch(url);
     if (response.status !== 200) {
         return null;
     }

package/dist/helpers/site-analyzer.js

@@ -1,5 +1,5 @@
-import fetch from "node-fetch";
 import { safe } from "./safe.js";
+import { originFetch } from "./origin-proxy.js";
 const EMPTY_FLAGS = {
     useGATracking: false,
     withGoogleOptimize: false,
@@ -78,7 +78,7 @@ function findUrl(html, host, pattern) {
     return `https://${host}${path}`;
 }
 async function fetchPage(url, signal) {
-    const result = await safe(fetch(url, { signal: signal }));
+    const result = await safe(originFetch(url, { signal }));
     if (!result.success)
         return null;
     const response = result.data;

package/dist/services/bundler/bundle-service-factory.d.ts

@@ -1,6 +1,7 @@
 import { BundleService } from "./bundle-service.js";
 export declare class BundleServiceFactory {
     private customerFolder?;
-    constructor(customerFolder?: string);
+    private additionalModulePaths;
+    constructor(customerFolder?: string, additionalModulePaths?: string[]);
     buildService(): BundleService;
 }

package/dist/services/bundler/bundle-service-factory.js

@@ -1,10 +1,12 @@
 import { BundleService } from "./bundle-service.js";
 export class BundleServiceFactory {
     customerFolder;
-    constructor(customerFolder) {
+    additionalModulePaths;
+    constructor(customerFolder, additionalModulePaths = []) {
         this.customerFolder = customerFolder;
+        this.additionalModulePaths = additionalModulePaths;
     }
     buildService() {
-        return new BundleService(this.customerFolder);
+        return new BundleService(this.customerFolder, this.additionalModulePaths);
     }
 }

package/dist/services/bundler/bundle-service.d.ts

@@ -1,10 +1,22 @@
 import { PluginBuild, LogLevel } from "esbuild";
 export type BundleEntryPoints = Record<string, string>;
 export type BundleBasePaths = Record<string, string>;
+/**
+ * Returns the source of a relative import that could not be resolved on disk, or `null` when the
+ * fallback has nothing to offer. Returning `null` lets esbuild report its original resolve error.
+ */
+export type BundleResolveFallback = (specifier: string) => Promise<string | null>;
 export declare class BundleService {
     private moduleDiscoveryDir;
-    constructor(moduleDiscoveryDir: string);
-    bundle({ entryPoints, basePaths, define, target, minify, logLevel, alias, platform, }: {
+    private additionalModulePaths;
+    /**
+     * @param moduleDiscoveryDir the directory bundled code resolves its own imports from
+     * @param additionalModulePaths extra `node_modules` directories to search, like `NODE_PATH`.
+     *   `sk` installs the packages a customer config declares under `dependencies` into its cache
+     *   rather than into the customer folder, so esbuild would otherwise never find them.
+     */
+    constructor(moduleDiscoveryDir: string, additionalModulePaths?: string[]);
+    bundle({ entryPoints, basePaths, define, target, minify, logLevel, alias, platform, resolveFallback, }: {
         entryPoints: BundleEntryPoints;
         basePaths?: BundleBasePaths;
         target?: string | string[];
@@ -13,6 +25,7 @@ export declare class BundleService {
         alias?: Record<string, string>;
         logLevel?: LogLevel;
         platform?: "browser" | "node" | "neutral";
+        resolveFallback?: BundleResolveFallback;
     }): Promise<string>;
     /**
      * Turns each alias target into an absolute path, resolved from the same directory the bundled
@@ -26,9 +39,24 @@ export declare class BundleService {
      * A target that is not installed stays a bare name, so esbuild reports it as before.
      */
     private resolveAliases;
+    /**
+     * Looks the target up the way the bundled code would: the customer folder first, then the
+     * additional module paths. Returns `null` when it is installed nowhere, so the bare name reaches
+     * esbuild and is reported as before.
+     */
+    private resolveAliasTarget;
     private entryPointsPlugin;
     baqendPlugin(basePaths: BundleBasePaths): {
         name: string;
         setup(build: PluginBuild): void;
     };
+    /**
+     * Resolves relative imports that exist nowhere in the customer folder through `resolveFallback`.
+     *
+     * A document handler shares its source with the Baqend app it is deployed to, so it may
+     * `require("./someModule")` a module that only lives in the app. Disk always wins: the fallback
+     * is only consulted after esbuild's own resolution has failed, and only for relative specifiers —
+     * a bare name is an npm package, and a missing one stays esbuild's error to report.
+     */
+    private resolveFallbackPlugin;
 }