@bigcommerce/stencil-cli 10.0.0 → 10.1.0

package/lib/cloudflared-binary.js

@@ -0,0 +1,266 @@
+import 'colors';
+import { execFile as nodeExecFile } from 'child_process';
+import crypto from 'crypto';
+import fsModule from 'fs';
+import os from 'os';
+import path from 'path';
+import { Transform } from 'stream';
+import { pipeline } from 'stream/promises';
+import { promisify } from 'util';
+import axios from 'axios';
+import inquirerModule from 'inquirer';
+import ProgressBar from 'progress';
+import semver from 'semver';
+import * as tar from 'tar';
+import CLOUDFLARED_MANIFEST from './cloudflared-manifest.js';
+
+// Cloudflare supports cloudflared releases for about one year. Raise this when bumping the pin.
+const MIN_VERSION = '2025.10.0';
+const PATH_ENV = 'STENCIL_CLOUDFLARED_PATH';
+const DOWNLOAD_BASE_URL = 'https://github.com/cloudflare/cloudflared/releases/download';
+const INSTALL_URL =
+    'https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/';
+
+/**
+ * Finds a cloudflared binary for Makeswift preview. Downloads a pinned release on first use.
+ */
+class CloudflaredBinary {
+    constructor({
+        fs = fsModule,
+        httpClient = axios,
+        execFile = promisify(nodeExecFile),
+        platform = process.platform,
+        arch = process.arch,
+        env = process.env,
+        homedir = os.homedir,
+        logger = console,
+        inquirer = inquirerModule,
+        stdin = process.stdin,
+        progressStream = process.stderr,
+        manifest = CLOUDFLARED_MANIFEST,
+        minVersion = MIN_VERSION,
+    } = {}) {
+        this._fs = fs;
+        this._httpClient = httpClient;
+        this._execFile = execFile;
+        this._platform = platform;
+        this._arch = arch;
+        this._env = env;
+        this._homedir = homedir;
+        this._logger = logger;
+        this._inquirer = inquirer;
+        this._stdin = stdin;
+        this._progressStream = progressStream;
+        this._manifest = manifest;
+        this._minVersion = minVersion;
+        this._resolvePromise = null;
+    }
+
+    /**
+     * Concurrent calls share one lookup and one download.
+     *
+     * @returns {Promise<string>} absolute path or command name for cloudflared
+     */
+    resolve() {
+        this._resolvePromise ??= this._resolve().catch((err) => {
+            // Let a later call try again.
+            this._resolvePromise = null;
+            throw err;
+        });
+        return this._resolvePromise;
+    }
+
+    async _resolve() {
+        const override = this._env[PATH_ENV];
+        if (override) {
+            return override;
+        }
+        if (await this._isPathBinaryUsable()) {
+            return 'cloudflared';
+        }
+        const asset = this._manifest.assets[`${this._platform}-${this._arch}`];
+        if (!asset) {
+            throw new Error(
+                `cloudflared is not available for ${this._platform}/${this._arch}. ` +
+                    `Install cloudflared and set ${PATH_ENV} to its path: ${INSTALL_URL}`,
+            );
+        }
+        const binaryPath = path.join(
+            this._getCacheDir(),
+            'stencil-cli',
+            'cloudflared',
+            this._manifest.version,
+            this._platform === 'win32' ? 'cloudflared.exe' : 'cloudflared',
+        );
+        if (await this._isFile(binaryPath)) {
+            return binaryPath;
+        }
+        await this._confirmDownload(path.dirname(binaryPath));
+        await this._download(asset, binaryPath);
+        return binaryPath;
+    }
+
+    async _isPathBinaryUsable() {
+        let output;
+        try {
+            const { stdout, stderr } = await this._execFile('cloudflared', ['--version'], {
+                timeout: 10000,
+            });
+            output = `${stdout}${stderr}`;
+        } catch {
+            return false;
+        }
+        const match = output.match(/cloudflared version (\S+)/);
+        const version = match && semver.coerce(match[1]);
+        if (version && semver.gte(version, this._minVersion)) {
+            return true;
+        }
+        const reason = version
+            ? `is version ${match[1]}, older than ${this._minVersion}`
+            : 'has an unknown version';
+        this._logger.log(
+            `${'Notice'.yellow}: cloudflared on your PATH ${reason}. ` +
+                `Using cloudflared ${this._manifest.version} managed by stencil-cli.`,
+        );
+        return false;
+    }
+
+    /**
+     * Asks the user before the download. Without a TTY there is nobody to ask, so do not download.
+     */
+    async _confirmDownload(dir) {
+        const { version } = this._manifest;
+        const notInstalled = `cloudflared was not found. Install cloudflared, or set ${PATH_ENV} to the path of cloudflared: ${INSTALL_URL}`;
+        if (!this._stdin?.isTTY) {
+            throw new Error(notInstalled);
+        }
+        const { install } = await this._inquirer.prompt([
+            {
+                type: 'confirm',
+                name: 'install',
+                message:
+                    `Makeswift preview needs cloudflared. Download cloudflared ${version} ` +
+                    `from GitHub to ${dir}?`,
+                default: true,
+            },
+        ]);
+        if (!install) {
+            throw new Error(notInstalled);
+        }
+    }
+
+    _getCacheDir() {
+        const home = this._homedir();
+        if (this._platform === 'darwin') {
+            return path.join(home, 'Library', 'Caches');
+        }
+        if (this._platform === 'win32') {
+            return this._env.LOCALAPPDATA || path.join(home, 'AppData', 'Local');
+        }
+        return this._env.XDG_CACHE_HOME || path.join(home, '.cache');
+    }
+
+    async _isFile(filePath) {
+        try {
+            return (await this._fs.promises.stat(filePath)).isFile();
+        } catch {
+            return false;
+        }
+    }
+
+    async _download(asset, binaryPath) {
+        const { version } = this._manifest;
+        const url = `${DOWNLOAD_BASE_URL}/${version}/${asset.name}`;
+        const dir = path.dirname(binaryPath);
+        // Unique temp names, so concurrent `stencil start` runs do not collide.
+        const suffix = `${process.pid}-${crypto.randomBytes(4).toString('hex')}`;
+        const tmpAsset = path.join(dir, `.${asset.name}.${suffix}.download`);
+        const tmpExtractDir = path.join(dir, `.extract.${suffix}`);
+        const tmpBinary = path.join(dir, `.${path.basename(binaryPath)}.${suffix}.tmp`);
+
+        this._logger.log(`Downloading cloudflared ${version} (first run only)...`);
+        try {
+            await this._fs.promises.mkdir(dir, { recursive: true });
+            const digest = await this._fetch(url, tmpAsset);
+            if (digest !== asset.sha256) {
+                throw new Error(
+                    `The cloudflared download from ${url} failed the checksum check ` +
+                        `(expected sha256 ${asset.sha256}, got ${digest}).`,
+                );
+            }
+            if (asset.name.endsWith('.tgz')) {
+                await this._extract(tmpAsset, tmpExtractDir, tmpBinary);
+            } else {
+                await this._fs.promises.rename(tmpAsset, tmpBinary);
+            }
+            if (this._platform !== 'win32') {
+                await this._fs.promises.chmod(tmpBinary, 0o755);
+            }
+            try {
+                await this._fs.promises.rename(tmpBinary, binaryPath);
+            } catch (err) {
+                // Another run can install it first. On Windows, rename fails if that file is in use.
+                if (!(await this._isFile(binaryPath))) {
+                    throw err;
+                }
+            }
+        } catch (err) {
+            err.message =
+                `Could not install cloudflared ${version}. ${err.message} ` +
+                `To use your own cloudflared, set ${PATH_ENV} to its path.`;
+            throw err;
+        } finally {
+            await Promise.all(
+                [tmpAsset, tmpExtractDir, tmpBinary].map((p) =>
+                    this._fs.promises.rm(p, { recursive: true, force: true }).catch(() => {}),
+                ),
+            );
+        }
+    }
+
+    /**
+     * Streams the URL to a file and returns the sha256 hex digest.
+     */
+    async _fetch(url, filePath) {
+        const response = await this._httpClient.get(url, {
+            responseType: 'stream',
+            timeout: 60000,
+        });
+        const hash = crypto.createHash('sha256');
+        const total = Number(response.headers?.['content-length']);
+        const bar =
+            this._progressStream?.isTTY && total > 0
+                ? new ProgressBar('cloudflared [:bar] :percent', {
+                      total,
+                      width: 30,
+                      stream: this._progressStream,
+                  })
+                : null;
+        const hasher = new Transform({
+            transform(chunk, encoding, callback) {
+                hash.update(chunk);
+                bar?.tick(chunk.length);
+                callback(null, chunk);
+            },
+        });
+        await pipeline(response.data, hasher, this._fs.createWriteStream(filePath));
+        return hash.digest('hex');
+    }
+
+    async _extract(archivePath, extractDir, binaryPath) {
+        await this._fs.promises.mkdir(extractDir, { recursive: true });
+        await tar.x({
+            file: archivePath,
+            cwd: extractDir,
+            filter: (entryPath) => entryPath.replace(/^\.\//, '') === 'cloudflared',
+        });
+        const extracted = path.join(extractDir, 'cloudflared');
+        if (!(await this._isFile(extracted))) {
+            throw new Error('The cloudflared archive does not contain a cloudflared file.');
+        }
+        await this._fs.promises.rename(extracted, binaryPath);
+    }
+}
+
+export { CloudflaredBinary, INSTALL_URL, MIN_VERSION, PATH_ENV };
+export default new CloudflaredBinary();

package/lib/cloudflared-manifest.js

@@ -0,0 +1,41 @@
+// Pinned cloudflared release. To update, set the version and copy each asset's sha256 from the
+// `digest` field of https://api.github.com/repos/cloudflare/cloudflared/releases/tags/<version>.
+const CLOUDFLARED_MANIFEST = {
+    version: '2026.10.0',
+    assets: {
+        'darwin-x64': {
+            name: 'cloudflared-darwin-amd64.tgz',
+            sha256: '903845b81828c8cb3c5d13d816a2de71c06a3da5785469df8eb0e1b736d92f9f',
+        },
+        'darwin-arm64': {
+            name: 'cloudflared-darwin-arm64.tgz',
+            sha256: 'a2f79ff7b9420aa537d74af239f376da170bbabeb529aec416002adac6a72e70',
+        },
+        'linux-x64': {
+            name: 'cloudflared-linux-amd64',
+            sha256: 'd33ff2d14475178d2012c2c56beba87389ac5ded27649519f198a7d3134a99db',
+        },
+        'linux-arm64': {
+            name: 'cloudflared-linux-arm64',
+            sha256: 'e6422b9d4f72d3194bc5a38676f13667c06666523217b842a877d72a80b5ac08',
+        },
+        'linux-arm': {
+            name: 'cloudflared-linux-arm',
+            sha256: '1dbe8e4ec17e74bb7f49cf91db6a4903bd0f9fe41984556c7503e40b765fd099',
+        },
+        'linux-ia32': {
+            name: 'cloudflared-linux-386',
+            sha256: 'f6fbd789e6ce9c824d4d560cbbfad2753d55ce398ece16b4c9fbf17271dceab3',
+        },
+        'win32-x64': {
+            name: 'cloudflared-windows-amd64.exe',
+            sha256: '86aee4017b26625cee8484c113558f48effa4cd47f7aa05fcf425604e5d2b23c',
+        },
+        'win32-ia32': {
+            name: 'cloudflared-windows-386.exe',
+            sha256: '0630a8779e9823a1a3b091698b8e71874e0f7b205559219f52fdd301466b5546',
+        },
+    },
+};
+
+export default CLOUDFLARED_MANIFEST;

package/lib/makeswift-proxy-health.js

@@ -0,0 +1,33 @@
+import NetworkUtils from './utils/NetworkUtils.js';
+
+const defaultNetworkUtils = new NetworkUtils();
+const HEALTH_PATH = '/api/makeswift/proxy-health';
+const REQUEST_TIMEOUT_MS = 5000;
+
+/**
+ * Checks if the storefront host is routed through the Makeswift proxy worker.
+ *
+ * @param {object} options
+ * @param {string} options.storeUrl
+ * @param {object} [deps]
+ * @returns {Promise<boolean>}
+ */
+async function isMakeswiftProxyActive({ storeUrl }, { networkUtils = defaultNetworkUtils } = {}) {
+    try {
+        const response = await networkUtils.sendApiRequest({
+            url: new URL(HEALTH_PATH, storeUrl).toString(),
+            timeout: REQUEST_TIMEOUT_MS,
+            // The preview session uses this host, so a redirect to another host does not count.
+            maxRedirects: 0,
+            responseType: 'text',
+        });
+        return response?.status === 200 && String(response.data).trim() === 'OK';
+    } catch {
+        return false;
+    }
+}
+
+export { isMakeswiftProxyActive };
+export default {
+    isMakeswiftProxyActive,
+};

package/lib/preview-proxy.js

@@ -0,0 +1,224 @@
+import crypto from 'crypto';
+import httpProxy from 'http-proxy';
+
+const PREVIEW_HEADER_PREFIX = 'x-stencil-preview-';
+const SESSION_HEADER = 'x-stencil-preview-session';
+const TIMESTAMP_HEADER = 'x-stencil-preview-timestamp';
+const SIGNATURE_HEADER = 'x-stencil-preview-signature';
+const LOOPBACK_HOSTNAMES = new Set(['localhost', '127.0.0.1', '[::1]']);
+
+/**
+ * Normalizes the request target.
+ *
+ * @param {string} rawUrl - request target from the incoming request
+ * @param {string} origin - storefront origin
+ * @returns {string | null} null when the target is not origin-form
+ */
+function getSignedPath(rawUrl, origin) {
+    if (typeof rawUrl !== 'string' || !rawUrl.startsWith('/')) {
+        return null;
+    }
+    try {
+        const url = new URL(`${origin}${rawUrl}`);
+        return url.origin === origin ? `${url.pathname}${url.search}` : null;
+    } catch {
+        return null;
+    }
+}
+
+function buildSigningString({ sessionId, timestamp, method, pathWithQuery }) {
+    return `${sessionId}\n${timestamp}\n${method.toUpperCase()}\n${pathWithQuery}`;
+}
+
+/**
+ * The HMAC key is the UTF-8 bytes of the hex access key string.
+ *
+ * @returns {Record<string, string>} the three proof headers
+ */
+function signPreviewRequest({ sessionId, accessKey, timestamp, method, pathWithQuery }) {
+    const signature = crypto
+        .createHmac('sha256', accessKey)
+        .update(buildSigningString({ sessionId, timestamp, method, pathWithQuery }))
+        .digest('hex');
+    return {
+        [SESSION_HEADER]: sessionId,
+        [TIMESTAMP_HEADER]: String(timestamp),
+        [SIGNATURE_HEADER]: signature,
+    };
+}
+
+function parseUrl(value) {
+    try {
+        return new URL(value);
+    } catch {
+        return null;
+    }
+}
+
+function isLoopbackHost(host) {
+    const url = typeof host === 'string' && host ? parseUrl(`http://${host}`) : null;
+    return url !== null && LOOPBACK_HOSTNAMES.has(url.hostname);
+}
+
+function isLoopbackUrl(value) {
+    const url = typeof value === 'string' ? parseUrl(value) : null;
+    return url !== null && LOOPBACK_HOSTNAMES.has(url.hostname);
+}
+
+function isExpectedLocalOrigin(value, localPort) {
+    const url = typeof value === 'string' ? parseUrl(value) : null;
+    return (
+        url !== null &&
+        url.protocol === 'http:' &&
+        LOOPBACK_HOSTNAMES.has(url.hostname) &&
+        url.port === String(Number(localPort))
+    );
+}
+
+/**
+ * Origin and Referer from the local front door point at the storefront instead.
+ * Other values do not change.
+ */
+function rewriteRequestHeaders(request, storefrontOrigin) {
+    const { origin, referer } = request.headers;
+    if (isLoopbackUrl(origin)) {
+        request.headers.origin = storefrontOrigin;
+    }
+    if (isLoopbackUrl(referer)) {
+        const { pathname, search } = new URL(referer);
+        request.headers.referer = `${storefrontOrigin}${pathname}${search}`;
+    }
+}
+
+/**
+ * Keeps the browser on the local front door when the storefront redirects to itself.
+ * A redirect to another host does not change.
+ */
+function rewriteLocation(location, storefrontUrl, localOrigin) {
+    if (typeof location !== 'string' || !/^(https?:)?\/\//i.test(location)) {
+        return location;
+    }
+    let url;
+    try {
+        url = new URL(location, storefrontUrl);
+    } catch {
+        return location;
+    }
+    if (url.host !== storefrontUrl.host || !/^https?:$/.test(url.protocol)) {
+        return location;
+    }
+    return `${localOrigin}${url.pathname}${url.search}${url.hash}`;
+}
+
+function sendText(response, status, message) {
+    response.writeHead(status, { 'content-type': 'text/plain; charset=utf-8' });
+    response.end(message);
+}
+
+/**
+ * Connect middleware for the local front door in Makeswift preview mode. It forwards each
+ * request to the storefront with a per-request proof, so the access key never leaves the CLI.
+ *
+ * @param {object} options
+ * @param {{ storeUrl: string, sessionId: string, accessKey: string }} options.previewSession -
+ *   read on each request, so a re-registered session is used at once
+ * @param {number} options.localPort - BrowserSync port for this preview server
+ * @param {Function} [options.proxyFactory]
+ * @param {{ error: Function }} [options.logger]
+ * @param {() => number} [options.now]
+ * @returns {(request: import('http').IncomingMessage, response: import('http').ServerResponse) => void}
+ */
+function createPreviewProxy({
+    previewSession,
+    localPort,
+    proxyFactory = httpProxy.createProxyServer,
+    logger = console,
+    now = Date.now,
+}) {
+    const storefrontUrl = new URL(previewSession.storeUrl);
+    const storefrontOrigin = storefrontUrl.origin;
+    const proxy = proxyFactory({
+        target: storefrontOrigin,
+        changeOrigin: true,
+        secure: true,
+        xfwd: false,
+    });
+
+    proxy.on('proxyReq', (proxyRequest, request) => {
+        // http-proxy collapses repeated slashes in the path. Send the exact signed path.
+        Object.assign(proxyRequest, { path: request.url });
+    });
+
+    proxy.on('proxyRes', (proxyResponse, request) => {
+        const { headers } = proxyResponse;
+        if (headers.location) {
+            headers.location = rewriteLocation(
+                headers.location,
+                storefrontUrl,
+                `http://${request.headers.host}`,
+            );
+        }
+    });
+
+    proxy.on('error', (error, _request, response) => {
+        logger.error(`Makeswift preview: the storefront request failed. ${error.message}`);
+        if (!response || typeof response.writeHead !== 'function') {
+            return;
+        }
+        if (response.headersSent) {
+            response.destroy();
+            return;
+        }
+        sendText(response, 502, 'Makeswift preview: the storefront request failed.');
+    });
+
+    return (request, response) => {
+        // Blocks DNS rebinding: another site cannot use the browser to send signed requests.
+        if (!isLoopbackHost(request.headers.host)) {
+            sendText(response, 403, 'Makeswift preview is available only on localhost.');
+            return;
+        }
+        if (
+            request.headers.origin !== undefined &&
+            !isExpectedLocalOrigin(request.headers.origin, localPort)
+        ) {
+            sendText(response, 403, 'Makeswift preview requests must come from this server.');
+            return;
+        }
+        const pathWithQuery = getSignedPath(request.url, storefrontOrigin);
+        if (pathWithQuery === null) {
+            sendText(response, 400, 'Bad request.');
+            return;
+        }
+
+        for (const name of Object.keys(request.headers)) {
+            if (name.startsWith(PREVIEW_HEADER_PREFIX)) {
+                delete request.headers[name];
+            }
+        }
+        delete request.headers.expect;
+        rewriteRequestHeaders(request, storefrontOrigin);
+        Object.assign(
+            request.headers,
+            signPreviewRequest({
+                sessionId: previewSession.sessionId,
+                accessKey: previewSession.accessKey,
+                timestamp: now(),
+                method: request.method,
+                pathWithQuery,
+            }),
+        );
+        request.url = pathWithQuery;
+
+        proxy.web(request, response);
+    };
+}
+
+export {
+    buildSigningString,
+    createPreviewProxy,
+    getSignedPath,
+    isLoopbackHost,
+    rewriteLocation,
+    signPreviewRequest,
+};

package/lib/stencil-start.js

@@ -16,6 +16,7 @@ import themeApiClientModule from './theme-api-client.js';
 import storeSettingsApiClientModule from './store-settings-api-client.js';
 import LangHelper from './lang-helper.js';
 import LangValidator from './lang/validator.js';
+import MakeswiftPreview from './MakeswiftPreview.js';
 
 class StencilStart {
     constructor({
@@ -33,6 +34,7 @@ class StencilStart {
         stencilPushUtils = stencilPushUtilsModule,
         logger = console,
         langValidator = new LangValidator(THEME_PATH),
+        makeswiftPreview = new MakeswiftPreview({ logger }),
     } = {}) {
         this._browserSync = browserSync;
         this._themeApiClient = themeApiClient;
@@ -48,6 +50,7 @@ class StencilStart {
         this._stencilPushUtils = stencilPushUtils;
         this._logger = logger;
         this._langValidator = langValidator;
+        this._makeswiftPreview = makeswiftPreview;
     }
 
     async run(cliOptions) {
@@ -71,9 +74,36 @@ class StencilStart {
             cliOptions,
             updatedStencilConfig,
         );
-        await this.startLocalServer(cliOptions, updatedStencilConfig);
-        this._logger.log(this.getStartUpInfo(updatedStencilConfig));
-        await this.startBrowserSync(cliOptions, browserSyncPort);
+        const previewStoreUrl = channelUrl || updatedStencilConfig.storeUrl;
+        const makeswiftPreview = await this._makeswiftPreview.isEnabled({
+            storeUrl: previewStoreUrl,
+            tunnel: cliOptions.tunnel,
+        });
+        if (makeswiftPreview) {
+            await this._makeswiftPreview.start({
+                localPort: browserSyncPort,
+                rendererPort: this.getRendererPort(browserSyncPort),
+                storeUrl: previewStoreUrl,
+                accessToken: updatedStencilConfig.accessToken,
+            });
+        }
+        try {
+            await this.startLocalServer(
+                cliOptions,
+                updatedStencilConfig,
+                this._makeswiftPreview.session?.secret,
+            );
+            this._logger.log(this.getStartUpInfo(updatedStencilConfig));
+            await this.startBrowserSync(cliOptions, browserSyncPort);
+        } catch (err) {
+            // The CLI exits on this error. Revoke the session before it does.
+            await this._makeswiftPreview.shutdown();
+            throw err;
+        }
+    }
+
+    getRendererPort(browserSyncPort) {
+        return Number(browserSyncPort) + 1;
     }
 
     async getStoreSettingsLocale(cliOptions, stencilConfig) {
@@ -141,8 +171,9 @@ class StencilStart {
      * @param {Object} stencilConfig
      * @return {Promise<any>}
      */
-    async startLocalServer(cliOptions, stencilConfig) {
+    async startLocalServer(cliOptions, stencilConfig, previewSecret) {
         return Server.create({
+            previewSecret,
             dotStencilFile: stencilConfig,
             variationIndex: this._themeConfigManager.variationIndex || 0,
             useCache: cliOptions.cache,
@@ -219,8 +250,9 @@ class StencilStart {
                 ignoreInitial: true,
                 ignored: watchIgnored.map((val) => path.join(themePath, val)),
             },
-            proxy: `localhost:${Number(browserSyncPort) + 1}`,
-            tunnel,
+            ...(this._makeswiftPreview.session
+                ? this._makeswiftPreview.getBrowserSyncOptions(browserSyncPort)
+                : { proxy: `localhost:${this.getRendererPort(browserSyncPort)}`, tunnel }),
         });
         // Handle manual reloading of browsers by typing 'rs';
         // Borrowed from https://github.com/remy/nodemon

package/lib/storefront-link-rewrite.js

@@ -0,0 +1,46 @@
+import { escapeRegExp } from 'lodash-es';
+
+// The link must start here. This stops a match on the "//host" part of "ftp://host" or
+// "https://other.test//host".
+const LINK_START = String.raw`(?<![\w:])`;
+
+// "https:", "http:", or nothing (a protocol-relative link).
+const SCHEME = '(?:https?:)?';
+
+// "//", or "\/\/" in JSON-escaped strings. The capture lets the output keep the same style.
+const SLASHES = String.raw`(\\?/\\?/)`;
+
+// The host must end here. This stops a match on a longer host ("host.evil.test", "host-2.com")
+// or on a different port ("host:8443"). A dot that ends a sentence ("Visit https://host.") is
+// not part of the host, so the link is still rewritten.
+const HOST_END = String.raw`(?![\w:-]|\.[^\s"'<])`;
+
+/**
+ * @param {string} storeHost - host (and port, if not default) of the storefront, e.g. `www.example.com`
+ * @returns {RegExp} matches absolute, protocol-relative, and JSON-escaped links to the host
+ */
+function buildStorefrontLinkPattern(storeHost) {
+    return new RegExp(LINK_START + SCHEME + SLASHES + escapeRegExp(storeHost) + HOST_END, 'gi');
+}
+
+/**
+ * Makes a BrowserSync rewrite rule that changes absolute storefront links in HTML to the local
+ * front door, so that navigation stays on localhost. Normal proxy mode does the same for the
+ * renderer host.
+ *
+ * BrowserSync (resp-modifier) calls `fn(req, res, ...String.prototype.replace callback args)`.
+ *
+ * @param {string} storeUrl - e.g. `https://www.example.com`
+ * @returns {{ match: RegExp, fn: Function }}
+ */
+function createStorefrontLinkRewriteRule(storeUrl) {
+    return {
+        match: buildStorefrontLinkPattern(new URL(storeUrl).host),
+        fn: (req, _res, _matched, slashes) => {
+            const localSlashes = slashes.includes('\\') ? '\\/\\/' : '//';
+            return `http:${localSlashes}${req.headers.host}`;
+        },
+    };
+}
+
+export { buildStorefrontLinkPattern, createStorefrontLinkRewriteRule };