@speedkit/cli 4.5.0 → 4.7.0

package/CHANGELOG.md

@@ -1,3 +1,27 @@
+# [4.7.0](https://gitlab.orestes.info/baqend/speed-kit-cli/compare/v4.6.0...v4.7.0) (2026-06-02)
+
+
+### Features
+
+* **customer-config:** improve add2cart disabling ([7d20650](https://gitlab.orestes.info/baqend/speed-kit-cli/commit/7d206503e27919375f78b93876dfa48686aaf5b5))
+
+# [4.6.0](https://gitlab.orestes.info/baqend/speed-kit-cli/compare/v4.5.0...v4.6.0) (2026-05-29)
+
+
+### Bug Fixes
+
+* **onboarding:** include product name in Windows browser version ([a058447](https://gitlab.orestes.info/baqend/speed-kit-cli/commit/a058447e3a0e3f26a57bc9bf4581943132f2183b))
+
+
+### Features
+
+* **customer-config:** add usercentrics handling ([c8b1da7](https://gitlab.orestes.info/baqend/speed-kit-cli/commit/c8b1da76a1e3bd629e029aa79fa8e5252c9faf10))
+* **extension-bridge:** write CLI state to devtools via chrome.storage.local ([0942178](https://gitlab.orestes.info/baqend/speed-kit-cli/commit/09421783de1116c5cf6c346230ed1b4625d8a584))
+* **local-cache-errors:** emit transform failures to devtools panel ([5989846](https://gitlab.orestes.info/baqend/speed-kit-cli/commit/598984629c7dc4de2cc9c064457a410f0e433e54))
+* **onboarding:** configurable mcp port ([ec562f4](https://gitlab.orestes.info/baqend/speed-kit-cli/commit/ec562f42f53ad0144c25373eaca1998a411b3b33))
+* **onboarding:** configurable mcp port ([6649b79](https://gitlab.orestes.info/baqend/speed-kit-cli/commit/6649b798ff935e7714c28d3c046a25d950d18f82))
+* **project:** claude ([0332a46](https://gitlab.orestes.info/baqend/speed-kit-cli/commit/0332a46778e5a4711d7919e53f53b74064679c00))
+
 # [4.5.0](https://gitlab.orestes.info/baqend/speed-kit-cli/compare/v4.4.2...v4.5.0) (2026-05-15)
 
 

package/README.md

@@ -21,7 +21,7 @@ $ npm install -g @speedkit/cli
 $ sk COMMAND
 running command...
 $ sk (--version)
-@speedkit/cli/4.5.0 linux-x64 node-v22.22.3
+@speedkit/cli/4.7.0 linux-x64 node-v22.22.3
 $ sk --help [COMMAND]
 USAGE
   $ sk COMMAND
@@ -383,7 +383,8 @@ Start a local dev environment for building and testing the Speed Kit configurati
 
 ```
 USAGE
-  $ sk onboarding CUSTOMERPATH [-c <value>] [-t] [-d <value>] [-l] [-p] [-v] [-s] [--headless]
+  $ sk onboarding CUSTOMERPATH [-c <value>] [-t] [-d <value>] [-l] [-p] [--debugPort <value>] [-v] [-s]
+    [--headless]
 
 ARGUMENTS
   CUSTOMERPATH  The customer config path
@@ -396,6 +397,8 @@ FLAGS
   -s, --ignoreContentSecurityPolicy  Removes header/meta "content-security-policy" for origin-responses
   -t, --useTestConfig                Override app with configured testApp
   -v, --verboseLevel                 Show all messages
+      --debugPort=<value>            [default: 9222] Chrome remote debugging port (only used with -p/--headless). Use
+                                     distinct ports to run multiple onboarding processes at once.
       --headless                     Run Chrome in headless mode (for CI environments). Implicitly enables remote
                                      debugging port.
 

package/dist/commands/onboarding.js

@@ -11,8 +11,8 @@ export default class Onboarding extends Command {
         `$ sk onboarding ${CLIParametersExample.CustomerPath} -${CLIParametersChar.ConfigName} ${CLIParametersExample.ConfigName} -${CLIParametersChar.Domain} ${CLIParametersExample.Domain}`,
     ];
     async run() {
-        const { args: { customerPath }, flags: { configName, domain, local, verboseLevel, ignoreContentSecurityPolicy, useTestConfig, debuggingPort, headless, }, } = await this.parse(Onboarding);
-        const service = await new OnboardingServiceFactory(new OnboardingContext(customerPath, configName, domain, local, ignoreContentSecurityPolicy, this.config.root, verboseLevel, useTestConfig, debuggingPort, headless), new CliConfig(this.config).load(customerPath)).getService();
+        const { args: { customerPath }, flags: { configName, domain, local, verboseLevel, ignoreContentSecurityPolicy, useTestConfig, debuggingPort, headless, debugPort, }, } = await this.parse(Onboarding);
+        const service = await new OnboardingServiceFactory(new OnboardingContext(customerPath, configName, domain, local, ignoreContentSecurityPolicy, this.config.root, verboseLevel, useTestConfig, debuggingPort, headless, debugPort), new CliConfig(this.config).load(customerPath)).getService();
         const shutdown = new AbortController();
         const onSignal = () => shutdown.abort();
         // `once`: a second Ctrl+C falls through to Node's default handler and

package/dist/helpers/site-analyzer.d.ts

@@ -6,6 +6,7 @@ export interface SiteAnalysisResult {
     includeServiceWorker: boolean;
     removeLazyLoading: boolean;
     hasSoftNavigations: boolean;
+    handleUsercentrics: boolean;
     shopSystem: DetectedShopSystem;
     hasInstallJs: boolean;
 }

package/dist/helpers/site-analyzer.js

@@ -7,6 +7,7 @@ const EMPTY_FLAGS = {
     includeServiceWorker: false,
     removeLazyLoading: false,
     hasSoftNavigations: false,
+    handleUsercentrics: false,
 };
 function detectFeatures(html, headers) {
     return {
@@ -16,6 +17,7 @@ function detectFeatures(html, headers) {
         includeServiceWorker: /navigator\.serviceWorker\.register|serviceWorker\.register/.test(html),
         removeLazyLoading: /loading=["']lazy["']|data-src=|class=["'][^"']*lazyload|lazysizes/.test(html),
         hasSoftNavigations: /__NEXT_DATA__|__NUXT__|vue-router|react-router|history\.pushState/.test(html),
+        handleUsercentrics: /uc-block(\.[\w-]+)*\.js|usercentrics\.eu|Usercentrics|data-usercentrics|__ucCmp|window\.UC_UI/.test(html),
     };
 }
 function mergeFeatures(results) {

package/dist/services/customer-config/customer-config-service-model.d.ts

@@ -48,6 +48,7 @@ export interface CustomerConfigSettings {
     activateCfRocketLoaderPlugin?: boolean;
     hasSoftNavigations?: boolean;
     convertSoftToHardNavigations?: boolean;
+    handleUsercentrics?: boolean;
     isPOV?: boolean;
     useDisabledSitesApproach?: boolean;
     shopSystemName?: string;

package/dist/services/customer-config/customer-config-service.js

@@ -251,6 +251,7 @@ export class CustomerConfigService {
         const gaTracking = resolve("useGATracking", true);
         const googleOptimize = resolve("withGoogleOptimize", false);
         const cfRocketLoader = resolve("activateCfRocketLoaderPlugin", false);
+        const usercentrics = resolve("handleUsercentrics", false);
         // Detectable features — sorted detected-first when analysis is available
         const detectableChoices = [
             {
@@ -293,6 +294,12 @@ export class CustomerConfigService {
                 checked: cfRocketLoader.checked,
                 description: "Handle Cloudflare Rocket Loader script deferral",
             },
+            {
+                name: `Usercentrics Handling${usercentrics.label}`,
+                value: "handleUsercentrics",
+                checked: usercentrics.checked,
+                description: "Set handleUsercentrics: true in DH Config — declares uc-block.bundle.js (Usercentrics CMP) as safe script",
+            },
         ];
         if (siteAnalysis) {
             const detectionRank = (name) => {
@@ -352,6 +359,7 @@ export class CustomerConfigService {
         const isPOV = has("isPOV");
         const withGoogleOptimize = has("withGoogleOptimize");
         const activateCfRocketLoaderPlugin = has("activateCfRocketLoaderPlugin");
+        const handleUsercentrics = has("handleUsercentrics");
         const useScrapingBee = has("useScrapingBee");
         const addDowntimeDetection = has("addDowntimeDetection");
         // Follow-up questions for features that need additional input
@@ -385,6 +393,7 @@ export class CustomerConfigService {
             useScrapingBee,
             withGoogleOptimize,
             activateCfRocketLoaderPlugin,
+            handleUsercentrics,
             hasSoftNavigations,
             convertSoftToHardNavigations,
             useDisabledSitesApproach,

package/dist/services/customer-config/templates/config_documentHandler.js.hbs

@@ -106,6 +106,9 @@ const config = {
 {{#if activateCfRocketLoaderPlugin}}
   handleRocketLoader: true,
 {{/if}}
+{{#if handleUsercentrics}}
+  handleUsercentrics: true,
+{{/if}}
 {{#if isShopify}}
   delayScriptPath: "/apps/speed-kit/speed-kit-dom-ready.js", // Shopify specific
 {{else}}

package/dist/services/customer-config/templates/config_dynamicStyles.css.hbs

@@ -99,11 +99,6 @@ html > body {
     }
   }
 
-  /* Prevent Add2Cart clicks: */
-  .dummy-add2cart-class {
-    pointer-events: none !important;
-  }
-
   /* Skeleton loading style: */
   .dummy-add2cart-class,
   .dummy-skeleton-container-class {
@@ -133,4 +128,11 @@ html > body {
     mask-image: linear-gradient(#000, #000), linear-gradient(#000, #000), linear-gradient(#000, #000);
     mask-repeat: no-repeat;
   }
+
+  /* Disable Add2Cart: */
+  .dummy-add2cart-class {
+    pointer-events: none !important;
+    opacity: 0.5 !important;
+    filter: grayscale(1) !important;
+  }
 }

package/dist/services/onboarding/browser/executable/executable-validator.js

@@ -51,10 +51,11 @@ export class ExecutableValidator {
     }
     getCurrentBrowserVersion() {
         // on windows executing chrome to gather the version will spawn a chromeProcess
-        // so we use a powershell instead
+        // so we use a powershell instead. Emit `<ProductName> <FileVersion>` so the
+        // output is shape-compatible with `chrome --version` on macOS/Linux —
+        // downstream consumers (isChromeBrowser, log lines) can stay OS-agnostic.
         if (this.userConfig.runtimeConfig.windows) {
-            return this.cli.execSync(`(Get-Item '${this.userConfig.chromePath}').VersionInfo.FileVersion`, { shell: "powershell.exe" });
-            // return this.userConfig.chromePath;
+            return this.cli.execSync(`$i = (Get-Item '${this.userConfig.chromePath}').VersionInfo; "$($i.ProductName) $($i.FileVersion)"`, { shell: "powershell.exe" });
         }
         return this.cli.execSync(`"${this.userConfig.chromePath}" --version`);
     }

package/dist/services/onboarding/browser/extension/devtools-extension-api.d.ts

@@ -1,7 +1,28 @@
 import { DevelopmentToolsMessage } from "../../onboarding-model.js";
+import { ExtensionBridge } from "./extension-bridge.js";
+/**
+ * In-memory queue of `DevelopmentToolsMessage` snapshots delivered to the
+ * devtools extension. Producers (factory, onboarding-service CDP listeners)
+ * call `addMessage`. Once an `ExtensionBridge` is attached, every change
+ * triggers a fire-and-forget push that mirrors the full message array into
+ * the extension's `chrome.storage.local`.
+ *
+ * Messages added before the bridge is attached stay queued — `setBridge`
+ * flushes them.
+ */
 export declare class DevtoolsExtensionApi {
     messages: DevelopmentToolsMessage[];
+    private bridge;
     getMessages(): DevelopmentToolsMessage[];
     addMessage(message: DevelopmentToolsMessage): void;
+    /**
+     * Replace the existing message with the same `id`, or push if none yet.
+     * Use this for "current state" messages (e.g. `localCacheError` carries
+     * the live error set, not a history of events) so the devtools panel
+     * doesn't have to dedupe.
+     */
+    upsertMessage(message: DevelopmentToolsMessage): void;
     clear(): void;
+    setBridge(bridge: ExtensionBridge): void;
+    private flush;
 }

package/dist/services/onboarding/browser/extension/devtools-extension-api.js

@@ -1,12 +1,50 @@
+/**
+ * In-memory queue of `DevelopmentToolsMessage` snapshots delivered to the
+ * devtools extension. Producers (factory, onboarding-service CDP listeners)
+ * call `addMessage`. Once an `ExtensionBridge` is attached, every change
+ * triggers a fire-and-forget push that mirrors the full message array into
+ * the extension's `chrome.storage.local`.
+ *
+ * Messages added before the bridge is attached stay queued — `setBridge`
+ * flushes them.
+ */
 export class DevtoolsExtensionApi {
     messages = [];
+    bridge = null;
     getMessages() {
         return this.messages;
     }
     addMessage(message) {
         this.messages.push(message);
+        void this.flush();
+    }
+    /**
+     * Replace the existing message with the same `id`, or push if none yet.
+     * Use this for "current state" messages (e.g. `localCacheError` carries
+     * the live error set, not a history of events) so the devtools panel
+     * doesn't have to dedupe.
+     */
+    upsertMessage(message) {
+        const idx = this.messages.findIndex((m) => m.id === message.id);
+        if (idx >= 0) {
+            this.messages[idx] = message;
+        }
+        else {
+            this.messages.push(message);
+        }
+        void this.flush();
     }
     clear() {
         this.messages = [];
+        void this.flush();
+    }
+    setBridge(bridge) {
+        this.bridge = bridge;
+        void this.flush();
+    }
+    async flush() {
+        if (!this.bridge)
+            return;
+        await this.bridge.writeMessages(this.messages);
     }
 }

package/dist/services/onboarding/browser/extension/extension-bridge.d.ts

@@ -0,0 +1,51 @@
+import { Browser } from "puppeteer";
+import { DevelopmentToolsMessage } from "../../onboarding-model.js";
+import { CliServiceInterface } from "../../../cli/index.js";
+/**
+ * Writes onboarding state (messages, status) into the devtools extension's
+ * chrome.storage.local via a CDP session against the extension's MV3
+ * service-worker target. The devtools extension subscribes via
+ * chrome.storage.onChanged. Replaces the legacy `window.skCliMessages` page
+ * injection — no more customer-visible global state.
+ *
+ * Lifecycle: construct once per browser, call `init()` after the browser is
+ * launched and the devtools extension has loaded, then call `writeMessages`
+ * whenever the message list changes.
+ */
+export declare class ExtensionBridge {
+    private readonly cli;
+    private browser;
+    private extensionId;
+    constructor(cli: CliServiceInterface);
+    /**
+     * Bind the bridge to a freshly-launched browser, discover the
+     * devtools-extension's service-worker target, and cache its extension ID.
+     * Polls for ~INIT_POLL_TIMEOUT_MS because MV3 service workers are
+     * sometimes not registered as targets until Chrome has finished loading
+     * the extension. Throws if no matching SW target is found in time.
+     */
+    init(browser: Browser): Promise<void>;
+    /**
+     * Write the current messages snapshot into chrome.storage.local. One retry
+     * on transient failures (MV3 service workers can briefly disappear during
+     * respawn). Failures are surfaced via `cli.writeError` but do not throw —
+     * a missed write is degraded UX, not a fatal onboarding failure.
+     */
+    writeMessages(messages: DevelopmentToolsMessage[]): Promise<void>;
+    private evaluateInServiceWorker;
+    /**
+     * Look up the service-worker target by cached extension ID. Returns null
+     * when the SW is dormant — callers handle that via retry.
+     */
+    private getServiceWorkerTarget;
+    /**
+     * Scan service-worker targets, evaluate `chrome.runtime.getManifest().name`
+     * on each, and return the first whose name matches the devtools-extension
+     * heuristic. We discover the extension by name (not by computing the ID
+     * from the unpacked path) because unpacked-extension IDs depend on the
+     * absolute path and OS path normalization.
+     */
+    private findDevtoolsServiceWorker;
+    private readManifestName;
+    private extractExtensionId;
+}

package/dist/services/onboarding/browser/extension/extension-bridge.js

@@ -0,0 +1,165 @@
+import { safe } from "../../../../helpers/safe.js";
+const STORAGE_KEY = "skCli";
+const PROTOCOL_VERSION = 1;
+const SW_LOOKUP_RETRY_MS = 250;
+const INIT_POLL_INTERVAL_MS = 200;
+const INIT_POLL_TIMEOUT_MS = 4000;
+// Same name heuristic as ExtensionValidator.handleDevtoolsExtension.
+const EXTENSION_NAME_MATCHERS = ["speed-kit devtools", "devtools extension"];
+/**
+ * Writes onboarding state (messages, status) into the devtools extension's
+ * chrome.storage.local via a CDP session against the extension's MV3
+ * service-worker target. The devtools extension subscribes via
+ * chrome.storage.onChanged. Replaces the legacy `window.skCliMessages` page
+ * injection — no more customer-visible global state.
+ *
+ * Lifecycle: construct once per browser, call `init()` after the browser is
+ * launched and the devtools extension has loaded, then call `writeMessages`
+ * whenever the message list changes.
+ */
+export class ExtensionBridge {
+    cli;
+    browser = null;
+    extensionId = null;
+    constructor(cli) {
+        this.cli = cli;
+    }
+    /**
+     * Bind the bridge to a freshly-launched browser, discover the
+     * devtools-extension's service-worker target, and cache its extension ID.
+     * Polls for ~INIT_POLL_TIMEOUT_MS because MV3 service workers are
+     * sometimes not registered as targets until Chrome has finished loading
+     * the extension. Throws if no matching SW target is found in time.
+     */
+    async init(browser) {
+        this.browser = browser;
+        const deadline = Date.now() + INIT_POLL_TIMEOUT_MS;
+        let target = await this.findDevtoolsServiceWorker();
+        while (!target && Date.now() < deadline) {
+            await sleep(INIT_POLL_INTERVAL_MS);
+            target = await this.findDevtoolsServiceWorker();
+        }
+        if (!target) {
+            throw new Error("ExtensionBridge: no devtools-extension service-worker target found " +
+                `within ${INIT_POLL_TIMEOUT_MS} ms. Confirm the extension is loaded ` +
+                "and its name matches one of: " +
+                EXTENSION_NAME_MATCHERS.join(", "));
+        }
+        this.extensionId = this.extractExtensionId(target.url());
+    }
+    /**
+     * Write the current messages snapshot into chrome.storage.local. One retry
+     * on transient failures (MV3 service workers can briefly disappear during
+     * respawn). Failures are surfaced via `cli.writeError` but do not throw —
+     * a missed write is degraded UX, not a fatal onboarding failure.
+     */
+    async writeMessages(messages) {
+        if (!this.browser || !this.extensionId) {
+            this.cli.writeWarning("ExtensionBridge.writeMessages called before init()");
+            return;
+        }
+        const payload = {
+            protocolVersion: PROTOCOL_VERSION,
+            writtenAt: new Date().toISOString(),
+            messages,
+        };
+        const first = await safe(this.evaluateInServiceWorker(payload));
+        if (first.success === true)
+            return;
+        await sleep(SW_LOOKUP_RETRY_MS);
+        const retry = await safe(this.evaluateInServiceWorker(payload));
+        if (retry.success !== true) {
+            this.cli.writeError(`ExtensionBridge.writeMessages failed: ${retry.error}`);
+        }
+    }
+    async evaluateInServiceWorker(payload) {
+        const target = await this.getServiceWorkerTarget();
+        if (!target) {
+            throw new Error("service-worker target not found");
+        }
+        const session = await target.createCDPSession();
+        try {
+            const expression = `chrome.storage.local.set(${JSON.stringify({
+                [STORAGE_KEY]: payload,
+            })})`;
+            const evalResult = await session.send("Runtime.evaluate", {
+                expression,
+                awaitPromise: true,
+                returnByValue: true,
+            });
+            if (evalResult.exceptionDetails) {
+                throw new Error(evalResult.exceptionDetails.text ||
+                    "Runtime.evaluate threw an unknown exception");
+            }
+        }
+        finally {
+            await safe(session.detach());
+        }
+    }
+    /**
+     * Look up the service-worker target by cached extension ID. Returns null
+     * when the SW is dormant — callers handle that via retry.
+     */
+    async getServiceWorkerTarget() {
+        if (!this.browser || !this.extensionId)
+            return null;
+        const prefix = `chrome-extension://${this.extensionId}/`;
+        for (const target of this.browser.targets()) {
+            if (target.type() === "service_worker" &&
+                target.url().startsWith(prefix)) {
+                return target;
+            }
+        }
+        return null;
+    }
+    /**
+     * Scan service-worker targets, evaluate `chrome.runtime.getManifest().name`
+     * on each, and return the first whose name matches the devtools-extension
+     * heuristic. We discover the extension by name (not by computing the ID
+     * from the unpacked path) because unpacked-extension IDs depend on the
+     * absolute path and OS path normalization.
+     */
+    async findDevtoolsServiceWorker() {
+        if (!this.browser)
+            return null;
+        const swTargets = this.browser
+            .targets()
+            .filter((t) => t.type() === "service_worker");
+        for (const target of swTargets) {
+            const name = await safe(this.readManifestName(target));
+            if (!name.success || !name.data)
+                continue;
+            const lower = name.data.toLowerCase();
+            if (EXTENSION_NAME_MATCHERS.some((m) => lower.includes(m))) {
+                return target;
+            }
+        }
+        return null;
+    }
+    async readManifestName(target) {
+        const session = await target.createCDPSession();
+        try {
+            const evalResult = await session.send("Runtime.evaluate", {
+                expression: "chrome.runtime.getManifest().name",
+                returnByValue: true,
+            });
+            if (evalResult.exceptionDetails)
+                return null;
+            const value = evalResult.result.value;
+            return typeof value === "string" ? value : null;
+        }
+        finally {
+            await safe(session.detach());
+        }
+    }
+    extractExtensionId(url) {
+        const match = url.match(/^chrome-extension:\/\/([a-p]{32})\//);
+        if (!match) {
+            throw new Error(`Could not extract extension ID from URL: ${url}`);
+        }
+        return match[1];
+    }
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/dist/services/onboarding/onboarding-model.d.ts

@@ -2,6 +2,7 @@ import { CDPSession } from "puppeteer";
 import { Protocol } from "puppeteer-core";
 import { UserCliConfig } from "../../helpers/cli-config.js";
 import { AbortResponse } from "./browser/abort-response.js";
+import { task } from "./todo-collector.js";
 import { VanillaPuppeteer } from "puppeteer-extra";
 import { Command } from "@oclif/core/command";
 export declare const BROWSER_EVENTS: {
@@ -38,9 +39,10 @@ export declare class BrowserContext {
     userAgent?: string;
     readonly debuggingPort: boolean;
     readonly headless: boolean;
+    readonly debugPort: number;
     readonly browserArgs: string[];
     readonly chromePath: string;
-    constructor(domain: string, browserVersionString?: string, chromeFlags?: string[], userConfig?: UserCliConfig, userAgent?: string, debuggingPort?: boolean, headless?: boolean);
+    constructor(domain: string, browserVersionString?: string, chromeFlags?: string[], userConfig?: UserCliConfig, userAgent?: string, debuggingPort?: boolean, headless?: boolean, debugPort?: number);
     private isChromeBrowser;
     private getBrowserExtensionPath;
     getPuppeteerLaunchOptions(): Parameters<VanillaPuppeteer["launch"]>[0];
@@ -60,12 +62,13 @@ export declare class OnboardingContext {
     readonly useTestConfig: boolean;
     readonly debuggingPort: boolean;
     readonly headless: boolean;
+    readonly debugPort: number;
     static flags: Record<string, Command.Flag>;
     readonly DEFAULT_DF_PATH = "https://www.baqend.com/speed-kit/latest/dynamic-fetcher.js";
     readonly DEFAULT_DOCUMENT_HANDLER_PATH = "https://www.baqend.com/speed-kit-handler/latest/DocumentHandler.js";
     readonly DEFAULT_SNIPPET_PATH = "https://www.baqend.com/speed-kit/latest/snippet.js";
     readonly DEFAULT_SW_PATH = "https://www.baqend.com/speed-kit/latest/sw.js";
-    constructor(customerPath: string, configName: string, domain: string, local: boolean, ignoreContentSecurityPolicy: boolean, cliPath: string, verboseLevel?: boolean, useTestConfig?: boolean, debuggingPort?: boolean, headless?: boolean);
+    constructor(customerPath: string, configName: string, domain: string, local: boolean, ignoreContentSecurityPolicy: boolean, cliPath: string, verboseLevel?: boolean, useTestConfig?: boolean, debuggingPort?: boolean, headless?: boolean, debugPort?: number);
 }
 export interface SpeedKitServerConfigAuthentication {
     password: string;
@@ -105,10 +108,45 @@ export interface SpeedKitServerConfig {
         variations: SpeedKitServerConfigVariation;
     };
 }
-export interface DevelopmentToolsMessage {
-    id: string;
-    data: any;
+export interface SkCliInfo {
+    version: string;
+    app: string;
+    customerConfigPath: string;
 }
+export interface AthenaInfo {
+    client: boolean;
+}
+export interface AppTokenInfo {
+    app: string;
+    token: string;
+}
+export interface LocalCacheError {
+    url: string;
+    assetUrl: string;
+    variation: string;
+    error: string;
+    stack: string | null;
+    occurredAt: number;
+}
+export type DevelopmentToolsMessage = {
+    id: "skCli";
+    data: SkCliInfo;
+} | {
+    id: "athena";
+    data: AthenaInfo;
+} | {
+    id: "todo";
+    data: task[];
+} | {
+    id: "appToken";
+    data: AppTokenInfo;
+} | {
+    id: "serviceWorker";
+    data: string;
+} | {
+    id: "localCacheError";
+    data: LocalCacheError[];
+};
 export declare const USER_AGENT: {
     DESKTOP: string;
     MOBILE: string;

package/dist/services/onboarding/onboarding-model.js

@@ -46,9 +46,10 @@ export class BrowserContext {
     userAgent;
     debuggingPort;
     headless;
+    debugPort;
     browserArgs;
     chromePath;
-    constructor(domain, browserVersionString = "unknown", chromeFlags, userConfig, userAgent, debuggingPort = false, headless = false) {
+    constructor(domain, browserVersionString = "unknown", chromeFlags, userConfig, userAgent, debuggingPort = false, headless = false, debugPort = 9222) {
         this.domain = domain;
         this.browserVersionString = browserVersionString;
         this.chromeFlags = chromeFlags;
@@ -56,6 +57,7 @@ export class BrowserContext {
         this.userAgent = userAgent;
         this.debuggingPort = debuggingPort;
         this.headless = headless;
+        this.debugPort = debugPort;
         this.domain = domain;
         this.chromeFlags = chromeFlags || [];
         this.chromePath = resolve(userConfig.chromePath);
@@ -106,7 +108,7 @@ export class BrowserContext {
             }
         }
         if (this.debuggingPort || this.headless) {
-            options.args.push("--remote-debugging-port=9222");
+            options.args.push(`--remote-debugging-port=${this.debugPort}`);
         }
         return options;
     }
@@ -122,6 +124,7 @@ export class OnboardingContext {
     useTestConfig;
     debuggingPort;
     headless;
+    debugPort;
     static flags = {
         ...CLI_CONFIG_NAME,
         ...CLI_CONFIG_IS_TEST,
@@ -139,6 +142,10 @@ export class OnboardingContext {
             default: false,
             description: "Enable remote debugging port (disables speculation rules/prerendering)",
         }),
+        debugPort: Flags.integer({
+            default: 9222,
+            description: "Chrome remote debugging port (only used with -p/--headless). Use distinct ports to run multiple onboarding processes at once.",
+        }),
         verboseLevel: Flags.boolean({
             char: "v",
             default: false,
@@ -158,7 +165,7 @@ export class OnboardingContext {
     DEFAULT_DOCUMENT_HANDLER_PATH = "https://www.baqend.com/speed-kit-handler/latest/DocumentHandler.js";
     DEFAULT_SNIPPET_PATH = "https://www.baqend.com/speed-kit/latest/snippet.js";
     DEFAULT_SW_PATH = "https://www.baqend.com/speed-kit/latest/sw.js";
-    constructor(customerPath, configName, domain, local, ignoreContentSecurityPolicy = false, cliPath, verboseLevel, useTestConfig = false, debuggingPort = false, headless = false) {
+    constructor(customerPath, configName, domain, local, ignoreContentSecurityPolicy = false, cliPath, verboseLevel, useTestConfig = false, debuggingPort = false, headless = false, debugPort = 9222) {
         this.customerPath = customerPath;
         this.configName = configName;
         this.domain = domain;
@@ -169,6 +176,7 @@ export class OnboardingContext {
         this.useTestConfig = useTestConfig;
         this.debuggingPort = debuggingPort;
         this.headless = headless;
+        this.debugPort = debugPort;
     }
 }
 export const USER_AGENT = {

package/dist/services/onboarding/onboarding-model.spec.d.ts

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

package/dist/services/onboarding/onboarding-model.spec.js

@@ -0,0 +1,28 @@
+import { expect } from "chai";
+import { describe, it } from "mocha";
+import { BrowserContext } from "./onboarding-model.js";
+// Providing chromeUserProfilePath keeps BrowserContext off the filesystem
+// (it skips the temp-profile branch in the constructor).
+const userConfig = {
+    chromePath: "/usr/bin/google-chrome",
+    chromeUserProfilePath: "/tmp/sk-test-profile",
+};
+function remoteDebuggingArg(debuggingPort, headless, debugPort) {
+    const context = new BrowserContext("example.com", "Chrome/120", [], userConfig, undefined, debuggingPort, headless, debugPort);
+    const args = context.getPuppeteerLaunchOptions().args;
+    return args.find((arg) => arg.startsWith("--remote-debugging-port="));
+}
+describe("BrowserContext.getPuppeteerLaunchOptions remote debugging port", () => {
+    it("defaults to port 9222 when debugging is enabled without a custom port", () => {
+        expect(remoteDebuggingArg(true, false)).to.equal("--remote-debugging-port=9222");
+    });
+    it("uses the provided debug port when debugging is enabled", () => {
+        expect(remoteDebuggingArg(true, false, 9223)).to.equal("--remote-debugging-port=9223");
+    });
+    it("uses the provided debug port in headless mode", () => {
+        expect(remoteDebuggingArg(false, true, 9224)).to.equal("--remote-debugging-port=9224");
+    });
+    it("omits the remote debugging port when debugging and headless are both off", () => {
+        expect(remoteDebuggingArg(false, false, 9223)).to.equal(undefined);
+    });
+});

package/dist/services/onboarding/onboarding-service-factory.js

@@ -27,6 +27,7 @@ import { InstallSpeedKitHtmlTemplate } from "./templates/install-speed-kit-html-
 import { InstallSpeedKitJsTemplate } from "./templates/install-speed-kit-js-template.js";
 import { ExtensionValidator } from "./browser/extension/extension-validator.js";
 import { DevtoolsExtensionApi } from "./browser/extension/devtools-extension-api.js";
+import { ExtensionBridge } from "./browser/extension/extension-bridge.js";
 import { TodoCollector } from "./todo-collector.js";
 import { Crawler } from "./virtual-orestes-app/crawler.js";
 import { VirtualOrestesApp } from "./virtual-orestes-app/index.js";
@@ -72,21 +73,30 @@ export class OnboardingServiceFactory {
         this.cliConfig.chromeExtensionPaths = extensionPaths.join(",");
         const browserValidator = new ExecutableValidator(this.cliConfig, cli);
         const browserVersionString = await browserValidator.validateOrInstall();
-        const browserContext = new BrowserContext(domainToStart, browserVersionString, customerConfig.chromeFlags || [], this.cliConfig, undefined, this.context.debuggingPort, this.context.headless);
+        const browserContext = new BrowserContext(domainToStart, browserVersionString, customerConfig.chromeFlags || [], this.cliConfig, undefined, this.context.debuggingPort, this.context.headless, this.context.debugPort);
         if (this.context.debuggingPort || this.context.headless) {
-            cli.writeWarning("Chrome remote debugging enabled on port 9222.");
+            cli.writeWarning(`Chrome remote debugging enabled on port ${this.context.debugPort}.`);
         }
         if (this.context.headless) {
             cli.writeWarning("Running in headless mode.");
         }
         const fileWatcher = new FileWatcher(cli, customerConfig, files, documentHandler, browserContext, cache);
         const athenaClient = (await this.getAthenaClient()) || null;
-        const fetchHandler = await this.getFetchEventHandler(files, customerConfig, documentHandler, cache, cli, browserContext, athenaClient);
         const messageHandler = await this.prepareMessagehandler(athenaClient, files, customerConfig);
-        return new OnboardingService(browserContext, customerConfig, fetchHandler, fileWatcher, cli, messageHandler);
+        const fetchHandler = await this.getFetchEventHandler(files, customerConfig, documentHandler, cache, cli, browserContext, athenaClient, messageHandler);
+        const extensionBridge = new ExtensionBridge(cli);
+        return new OnboardingService(browserContext, customerConfig, fetchHandler, fileWatcher, cli, messageHandler, extensionBridge);
     }
     async prepareMessagehandler(athenaClient, files, customerConfig) {
         const messageHandler = new DevtoolsExtensionApi();
+        messageHandler.addMessage({
+            id: "skCli",
+            data: {
+                version: this.cliConfig.runtimeConfig.version,
+                app: customerConfig.app,
+                customerConfigPath: path.resolve(this.context.customerPath, this.context.configName),
+            },
+        });
         messageHandler.addMessage({
             id: "athena",
             data: { client: !!athenaClient },
@@ -135,7 +145,7 @@ export class OnboardingServiceFactory {
         const configApiContext = new ConfigApiContext(app);
         return new ConfigApiServiceFactory(configApiContext).getService();
     }
-    async getFetchEventHandler(files, customerConfig, documentHandler, cache, cli, browserContext, athenaClient) {
+    async getFetchEventHandler(files, customerConfig, documentHandler, cache, cli, browserContext, athenaClient, messageHandler) {
         const configApi = this.getConfigApi(customerConfig.app);
         const serverConfig = await this.getSpeedKitServerConfig(configApi, cli);
         const agent = this.getCrawlerAgent(customerConfig, cli);
@@ -156,7 +166,7 @@ export class OnboardingServiceFactory {
             new DashboardRequest(new Dashboard(customerConfig, parameterQueryBuilder, athenaClient, requestDiffService, new DiffAgainstCurrentPage(DiffService, documentHandler, crawler, cli), cache)),
         ];
         if (this.context.local) {
-            const orestesApp = new VirtualOrestesApp(customerConfig, crawler, documentHandler, cache, cli);
+            const orestesApp = new VirtualOrestesApp(customerConfig, crawler, documentHandler, cache, cli, messageHandler);
             handlers.push(new SpeedKitAssetRequest(customerConfig, orestesApp), new SpeedKitRumPiRequest(customerConfig, cache, cli));
         }
         return new FetchEventHandler(handlers, customerConfig, cli, configApi);

package/dist/services/onboarding/onboarding-service.d.ts

@@ -4,6 +4,7 @@ import { FetchEventHandler } from "./fetch-event-handler.js";
 import { FileWatcher } from "./file-events/file-watcher.js";
 import { CliService } from "../cli/index.js";
 import { DevtoolsExtensionApi } from "./browser/extension/devtools-extension-api.js";
+import { ExtensionBridge } from "./browser/extension/extension-bridge.js";
 /**
  * Represents the OnboardingService which is responsible for setting up the browser to test a config using Puppeteer.
  */
@@ -14,8 +15,9 @@ export declare class OnboardingService {
     private fileWatcher;
     private cli;
     private developmentToolsMessages;
+    private extensionBridge;
     private reinstallOnNextNavigate;
-    constructor(browserContext: BrowserContext, customerConfig: CustomerConfig, fetchEventHandler: FetchEventHandler, fileWatcher: FileWatcher, cli: CliService, developmentToolsMessages: DevtoolsExtensionApi);
+    constructor(browserContext: BrowserContext, customerConfig: CustomerConfig, fetchEventHandler: FetchEventHandler, fileWatcher: FileWatcher, cli: CliService, developmentToolsMessages: DevtoolsExtensionApi, extensionBridge: ExtensionBridge);
     /**
      * Prepare the puppeteer browser, wire event listeners, navigate to the
      * install page, then block until either the caller aborts the signal
@@ -25,6 +27,14 @@ export declare class OnboardingService {
     run(externalSignal: AbortSignal): Promise<void>;
     private prepareBrowser;
     private preparePage;
+    /**
+     * Bind the injected ExtensionBridge to the freshly-launched browser so
+     * message updates are mirrored into the devtools extension's
+     * `chrome.storage.local`. A failure here is non-fatal: onboarding still
+     * proceeds, but the devtools panel will not receive live updates from
+     * sk-cli.
+     */
+    private attachExtensionBridge;
     private findPage;
     private prepareCleanState;
     private reinstallSpeedKit;

package/dist/services/onboarding/onboarding-service.js

@@ -11,14 +11,16 @@ export class OnboardingService {
     fileWatcher;
     cli;
     developmentToolsMessages;
+    extensionBridge;
     reinstallOnNextNavigate = false;
-    constructor(browserContext, customerConfig, fetchEventHandler, fileWatcher, cli, developmentToolsMessages) {
+    constructor(browserContext, customerConfig, fetchEventHandler, fileWatcher, cli, developmentToolsMessages, extensionBridge) {
         this.browserContext = browserContext;
         this.customerConfig = customerConfig;
         this.fetchEventHandler = fetchEventHandler;
         this.fileWatcher = fileWatcher;
         this.cli = cli;
         this.developmentToolsMessages = developmentToolsMessages;
+        this.extensionBridge = extensionBridge;
     }
     /**
      * Prepare the puppeteer browser, wire event listeners, navigate to the
@@ -34,6 +36,7 @@ export class OnboardingService {
             localController.signal,
         ]);
         const browser = await this.prepareBrowser(localController);
+        await this.attachExtensionBridge(browser);
         const page = await this.preparePage(browser, shutdownSignal);
         this.cli.successAction("ONBOARDING:PREPARE:BROWSER");
         await this.navigate(page, `${this.customerConfig.scope}speed-kit-install.html?url=${this.customerConfig.scope}`);
@@ -58,17 +61,23 @@ export class OnboardingService {
         await safe(this.prepareCleanState(page));
         this.registerFileWatcher(page, shutdownSignal);
         this.registerReinstallSpeedKitOnNavigate(page);
-        this.developmentToolsMessages.addMessage({
-            id: "cli",
-            data: `config loaded for app "${this.customerConfig.app}"`,
-        });
-        const messages = this.developmentToolsMessages.messages;
-        await page.evaluateOnNewDocument((messages) => {
-            // @ts-expect-error unknown method getSkCliMessages
-            window.skCliMessages = messages;
-        }, messages);
         return page;
     }
+    /**
+     * Bind the injected ExtensionBridge to the freshly-launched browser so
+     * message updates are mirrored into the devtools extension's
+     * `chrome.storage.local`. A failure here is non-fatal: onboarding still
+     * proceeds, but the devtools panel will not receive live updates from
+     * sk-cli.
+     */
+    async attachExtensionBridge(browser) {
+        const result = await safe(this.extensionBridge.init(browser));
+        if (result.success !== true) {
+            this.cli.writeWarning(`ExtensionBridge unavailable, devtools panel will not receive live updates: ${result.error}`);
+            return;
+        }
+        this.developmentToolsMessages.setBridge(this.extensionBridge);
+    }
     async findPage(browser) {
         if (!browser)
             throw new Error("Please start a browser first.");

package/dist/services/onboarding/virtual-orestes-app/index.d.ts

@@ -5,15 +5,22 @@ import { Cache } from "../request-cache/cache.js";
 import { CliService } from "../../cli/index.js";
 import { Crawler } from "./crawler.js";
 import { CustomerConfig } from "../../integration-api/index.js";
+import { DevtoolsExtensionApi } from "../browser/extension/devtools-extension-api.js";
 export declare class VirtualOrestesApp {
     private customerConfig;
     private crawler;
     private documentHandler;
     private cache;
     private cli;
-    constructor(customerConfig: CustomerConfig, crawler: Crawler, documentHandler: DocumentHandlerServer, cache: Cache, cli: CliService);
+    private developmentToolsMessages;
+    private localCacheErrors;
+    constructor(customerConfig: CustomerConfig, crawler: Crawler, documentHandler: DocumentHandlerServer, cache: Cache, cli: CliService, developmentToolsMessages: DevtoolsExtensionApi);
     fetchAssetResponse(event: Protocol.Fetch.RequestPausedEvent): Promise<Partial<Protocol.Fetch.FulfillRequestRequest> | AbortResponse>;
     private getResponseText;
+    private localCacheErrorKey;
+    private recordLocalCacheError;
+    private clearLocalCacheError;
+    private emitLocalCacheErrors;
     private returnErrorResponse;
     private convertResponseHeadersToOrestesFormat;
     private returnRedirect;

package/dist/services/onboarding/virtual-orestes-app/index.js

@@ -13,12 +13,19 @@ export class VirtualOrestesApp {
     documentHandler;
     cache;
     cli;
-    constructor(customerConfig, crawler, documentHandler, cache, cli) {
+    developmentToolsMessages;
+    // Local-mode transform errors keyed by `${url}|${variation}`. Emitted to
+    // the devtools panel via DevtoolsExtensionApi.upsertMessage so the panel
+    // can surface an "error for this URL" affordance in the Causes & sources
+    // card. Cleared per-URL on the next successful transform.
+    localCacheErrors = new Map();
+    constructor(customerConfig, crawler, documentHandler, cache, cli, developmentToolsMessages) {
         this.customerConfig = customerConfig;
         this.crawler = crawler;
         this.documentHandler = documentHandler;
         this.cache = cache;
         this.cli = cli;
+        this.developmentToolsMessages = developmentToolsMessages;
     }
     async fetchAssetResponse(event) {
         const originUrl = this.getAssetUrl(event.request.url);
@@ -56,8 +63,10 @@ export class VirtualOrestesApp {
         }
         const customResponse = await safe(this.documentHandler.transform(`text/html;charset=${textEncoding}`, responseContent, variation, originUrl, this.convertResponseHeadersToOrestesFormat(response)));
         if (customResponse.success === false) {
+            this.recordLocalCacheError(originUrl, event.request.url, variation, customResponse);
             return this.returnErrorResponse(customResponse, customHeaders);
         }
+        this.clearLocalCacheError(originUrl, variation);
         const skResponse = customResponse.data;
         if (!Buffer.isBuffer(skResponse.body) && this.customerConfig.forceInstall) {
             skResponse.body = this.rewriteInstallResource(skResponse.body);
@@ -108,6 +117,33 @@ export class VirtualOrestesApp {
             textEncoding: encodingFromBodyMeta ?? encodingFromHeader,
         };
     }
+    localCacheErrorKey(url, variation) {
+        return `${url}|${variation}`;
+    }
+    recordLocalCacheError(url, assetUrl, variation, customResponse) {
+        this.localCacheErrors.set(this.localCacheErrorKey(url, variation), {
+            url,
+            assetUrl,
+            variation,
+            error: customResponse.error,
+            stack: customResponse.errorObj?.stack ?? null,
+            occurredAt: Date.now(),
+        });
+        this.emitLocalCacheErrors();
+    }
+    clearLocalCacheError(url, variation) {
+        const key = this.localCacheErrorKey(url, variation);
+        if (!this.localCacheErrors.has(key))
+            return;
+        this.localCacheErrors.delete(key);
+        this.emitLocalCacheErrors();
+    }
+    emitLocalCacheErrors() {
+        this.developmentToolsMessages.upsertMessage({
+            id: "localCacheError",
+            data: [...this.localCacheErrors.values()],
+        });
+    }
     returnErrorResponse(customResponse, customHeaders) {
         const message = `Could not transform html: - ${customResponse.error}`;
         this.cli.writeError(`[VirtualOrestes]: ${message}`);

package/oclif.manifest.json

@@ -500,6 +500,14 @@
           "allowNo": false,
           "type": "boolean"
         },
+        "debugPort": {
+          "description": "Chrome remote debugging port (only used with -p/--headless). Use distinct ports to run multiple onboarding processes at once.",
+          "name": "debugPort",
+          "default": 9222,
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
         "verboseLevel": {
           "char": "v",
           "description": "Show all messages",
@@ -751,5 +759,5 @@
       ]
     }
   },
-  "version": "4.5.0"
+  "version": "4.7.0"
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@speedkit/cli",
   "description": "Speed Kit CLI",
-  "version": "4.5.0",
+  "version": "4.7.0",
   "author": {
     "name": "Baqend.com",
     "email": "info@baqend.com"