@speedkit/cli 4.20.3 → 4.20.5

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+## [4.20.5](https://gitlab.orestes.info/baqend/speed-kit-cli/compare/v4.20.4...v4.20.5) (2026-08-10)
+
+
+### Bug Fixes
+
+* **onboarding:** keep watching a config file after git replaces it ([ef2571a](https://gitlab.orestes.info/baqend/speed-kit-cli/commit/ef2571a5fa07862382c338096e3311c107f20a74))
+
+## [4.20.4](https://gitlab.orestes.info/baqend/speed-kit-cli/compare/v4.20.3...v4.20.4) (2026-08-10)
+
+
+### Bug Fixes
+
+* **onboarding:** detect and repair deployed service worker takeovers ([6d61ae7](https://gitlab.orestes.info/baqend/speed-kit-cli/commit/6d61ae71bab7dc2bbd4926d0c17fc8505d7f523e))
+
 ## [4.20.3](https://gitlab.orestes.info/baqend/speed-kit-cli/compare/v4.20.2...v4.20.3) (2026-08-07)
 
 

package/README.md

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

package/dist/services/integration-api/spec/file-watch.spec.d.ts

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

package/dist/services/integration-api/spec/file-watch.spec.js

@@ -0,0 +1,81 @@
+import { expect } from "chai";
+import { describe, it, afterEach } from "mocha";
+import { mkdtempSync, rmSync, unlinkSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+// via the model barrel, not struct/file.js directly: the struct modules form an
+// import cycle that only resolves in this order.
+import { File } from "../integration-api-model.js";
+// chokidar needs a real filesystem, so these run against a temp dir rather than memfs.
+const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/** Wait until the change callback has fired at least `count` times. */
+async function waitForCalls(getCalls, count, timeoutMs = 5000) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        if (getCalls() >= count)
+            return;
+        await delay(50);
+    }
+}
+describe("File onChange", function () {
+    // real filesystem events plus chokidar's write-finish debounce
+    this.timeout(20000);
+    let dir;
+    let controller;
+    afterEach(() => {
+        controller?.abort();
+        controller = undefined;
+        if (dir) {
+            rmSync(dir, { recursive: true, force: true });
+            dir = undefined;
+        }
+    });
+    it("keeps reporting edits after the file is replaced instead of written in place", async () => {
+        dir = mkdtempSync(join(tmpdir(), "sk-file-watch-"));
+        const path = join(dir, "config_documentHandler.js");
+        writeFileSync(path, "v0");
+        const file = new File("config_documentHandler", path, "v0");
+        controller = new AbortController();
+        let calls = 0;
+        file.onChange(async () => {
+            calls += 1;
+        }, { signal: controller.signal });
+        await delay(700); // let the watcher attach
+        writeFileSync(path, "v1");
+        await waitForCalls(() => calls, 1);
+        expect(calls, "an in-place write is reported").to.be.at.least(1);
+        // git checkout / reset / rebase / stash / pull replace the file rather than
+        // writing into it. A single-file watch stops firing for good at this point.
+        const callsBeforeReplace = calls;
+        unlinkSync(path);
+        writeFileSync(path, "v2");
+        await waitForCalls(() => calls, callsBeforeReplace + 1);
+        expect(calls, "the replacement itself is reported").to.be.at.least(callsBeforeReplace + 1);
+        // The regression: every edit after the replacement used to be dropped, so
+        // onboarding kept serving the previous build until it was restarted.
+        const callsAfterReplace = calls;
+        writeFileSync(path, "v3");
+        await waitForCalls(() => calls, callsAfterReplace + 1);
+        expect(calls, "an edit after the replacement is still reported").to.be.at.least(callsAfterReplace + 1);
+    });
+    it("ignores changes to sibling files in the same directory", async () => {
+        dir = mkdtempSync(join(tmpdir(), "sk-file-watch-"));
+        const path = join(dir, "config_documentHandler.js");
+        const sibling = join(dir, "config_SpeedKit.js");
+        writeFileSync(path, "v0");
+        writeFileSync(sibling, "other");
+        const file = new File("config_documentHandler", path, "v0");
+        controller = new AbortController();
+        let calls = 0;
+        file.onChange(async () => {
+            calls += 1;
+        }, { signal: controller.signal });
+        await delay(700);
+        writeFileSync(sibling, "other-changed");
+        await delay(900);
+        expect(calls, "a sibling write is not reported").to.equal(0);
+        writeFileSync(path, "v1");
+        await waitForCalls(() => calls, 1);
+        expect(calls, "the watched file is still reported").to.be.at.least(1);
+    });
+});

package/dist/services/integration-api/struct/file.js

@@ -1,4 +1,5 @@
 import { readFile, unlink, writeFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
 import { watch as chokidarWatch } from "chokidar";
 import { FILE_TYPE, } from "../integration-api-model.js";
 export class File {
@@ -47,15 +48,26 @@ export class File {
         if (signal?.aborted) {
             return;
         }
-        // chokidar over node's fs.watch: handles atomic write-then-rename
-        // (Claude Code, VS Code's atomicSave, vim writebackup, …) which fs.watch
-        // misses because inotify is inode-bound and the new file gets a new inode.
-        const watcher = chokidarWatch(this.path, {
+        // Watch the containing directory, not the file: a single-file watch stops
+        // firing for good once the file is *replaced* rather than written in place,
+        // which is what git does on checkout/reset/rebase/stash/pull. The replace
+        // itself still arrives, so the breakage is silent — every later edit is
+        // dropped, no rebuild and no cache clear run, and onboarding keeps serving
+        // the previous build until it is restarted.
+        // depth 0 keeps this to the directory's own entries, and chokidar's atomic
+        // option still folds write-then-rename (Claude Code, VS Code atomicSave,
+        // vim writebackup, …) into a single change event.
+        const target = resolve(this.path);
+        const watcher = chokidarWatch(dirname(target), {
             ignoreInitial: true,
             atomic: true,
+            depth: 0,
             awaitWriteFinish: { stabilityThreshold: 200, pollInterval: 50 },
         });
-        const handle = async () => {
+        const handle = async (changedPath) => {
+            if (resolve(changedPath) !== target) {
+                return;
+            }
             const content = await readFile(this.path, "utf-8");
             if (content === this.content) {
                 return;

package/dist/services/onboarding/browser/baqend-response.js

@@ -1,3 +1,12 @@
+/**
+ * Makes a value safe for Fetch.fulfillRequest: collapse line breaks and strip
+ * characters outside latin-1, either of which Chrome rejects as "Invalid header".
+ */
+function sanitizeHeaderValue(value) {
+    return String(value)
+        .replace(/[\r\n]+/g, " ")
+        .replace(/[^\x20-\xff\t]/g, "?");
+}
 const DEFAULT_HEADERS = [
     { name: "Date", value: new Date().toUTCString() },
     { name: "Content-Encoding", value: "identity" },
@@ -24,19 +33,28 @@ export class BaqendResponse {
             : Buffer.from(body).toString("base64");
     }
     setHeader(name, value) {
+        const sanitized = sanitizeHeaderValue(value);
         for (const header of this.responseHeaders) {
             if (header.name === name) {
-                header.value = value;
+                header.value = sanitized;
                 return;
             }
         }
-        this.responseHeaders.push({ name, value });
+        this.responseHeaders.push({ name, value: sanitized });
     }
     addCustomHeaders(headers) {
+        // Fetch.fulfillRequest rejects header values with line breaks or
+        // non-latin-1 characters ("Invalid header") — e.g. an error message with
+        // a newline placed into x-error left the request hanging in paused state.
+        for (const header of headers) {
+            header.value = sanitizeHeaderValue(header.value);
+        }
         if (!headers?.find((o) => o.name === "Cache-Control")) {
             headers.push({
                 name: "Cache-Control",
-                value: "max-age=0, nocache, nostore",
+                // NOTE: was "nocache, nostore" — invalid directive names that browsers
+                // ignore, leaving locally served responses cacheable.
+                value: "max-age=0, no-cache, no-store",
             });
         }
         const origin = headers?.find((o) => o.name.toLowerCase() === "origin")?.value;

package/dist/services/onboarding/fetch-event-handler.js

@@ -41,10 +41,17 @@ export class FetchEventHandler {
             if (response.errorObj) {
                 this.cli.writeError(`error on ${event.request.url}`);
                 this.cli.writeError(`${response.errorObj.message}`);
-                return;
             }
-            this.cli.writeError(`error on ${target.url()}`);
-            this.cli.writeError(JSON.stringify(response.errorObj));
+            else {
+                this.cli.writeError(`error on ${target.url()}`);
+                this.cli.writeError(JSON.stringify(response.errorObj));
+            }
+            // A request left in paused state hangs until the browser times out.
+            // Fail it explicitly so the page sees a network error instead.
+            await safe(cdpSession.send("Fetch.failRequest", {
+                requestId: event.requestId,
+                errorReason: "Failed",
+            }));
         });
     }
     canHandlePattern(fetchEventHandler, url, resourceType, requestStage) {

package/dist/services/onboarding/fetch-events/speed-kit-service-worker-js.d.ts

@@ -11,6 +11,14 @@ export declare class SpeedKitServiceWorkerJs implements FetchRequestPausedEventH
     private customerConfig;
     private serviceWorker;
     readonly patterns: Protocol.Fetch.RequestPattern[];
+    /**
+     * Timestamp of the last locally served sw.js. Chrome's SW update checker
+     * fetches scripts in the browser process, outside CDP Fetch interception —
+     * an update that slips through installs the DEPLOYED build. A SW version
+     * that activates without a recent local serve is such a takeover; the
+     * OnboardingService uses this timestamp to detect and repair it.
+     */
+    lastServedAt: number;
     constructor(customerConfig: CustomerConfig, serviceWorker: FileInterface);
     handle(): Promise<Partial<Protocol.Fetch.FulfillRequestRequest>>;
 }

package/dist/services/onboarding/fetch-events/speed-kit-service-worker-js.js

@@ -9,6 +9,14 @@ export class SpeedKitServiceWorkerJs {
     customerConfig;
     serviceWorker;
     patterns;
+    /**
+     * Timestamp of the last locally served sw.js. Chrome's SW update checker
+     * fetches scripts in the browser process, outside CDP Fetch interception —
+     * an update that slips through installs the DEPLOYED build. A SW version
+     * that activates without a recent local serve is such a takeover; the
+     * OnboardingService uses this timestamp to detect and repair it.
+     */
+    lastServedAt = 0;
     constructor(customerConfig, serviceWorker) {
         this.customerConfig = customerConfig;
         this.serviceWorker = serviceWorker;
@@ -20,6 +28,7 @@ export class SpeedKitServiceWorkerJs {
         ];
     }
     async handle() {
+        this.lastServedAt = Date.now();
         return new BaqendResponse(this.serviceWorker.getContent(), "text/javascript; charset=utf-8");
     }
 }

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

@@ -16,6 +16,7 @@ export declare const CDP_SESSION: {
     EVENTS: {
         SERVICE_WORKER: {
             REGISTRATION_UPDATED: string;
+            VERSION_UPDATED: string;
         };
     };
     MESSAGE: {

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

@@ -41,6 +41,7 @@ export const CDP_SESSION = {
     EVENTS: {
         SERVICE_WORKER: {
             REGISTRATION_UPDATED: "ServiceWorker.workerRegistrationUpdated",
+            VERSION_UPDATED: "ServiceWorker.workerVersionUpdated",
         },
     },
     MESSAGE: {

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

@@ -83,9 +83,10 @@ export class OnboardingServiceFactory {
         const fileWatcher = new FileWatcher(cli, customerConfig, files, documentHandler, browserContext, cache);
         const athenaClient = (await this.getAthenaClient(customerConfig.app)) || null;
         const messageHandler = await this.prepareMessagehandler(athenaClient, files, customerConfig);
-        const fetchHandler = await this.getFetchEventHandler(files, customerConfig, documentHandler, cache, cli, browserContext, athenaClient, messageHandler, fileWatcher);
+        const speedKitServiceWorkerJs = new SpeedKitServiceWorkerJs(customerConfig, files.getByName(INTEGRATION_FILES.CUSTOM.SW));
+        const fetchHandler = await this.getFetchEventHandler(files, customerConfig, documentHandler, cache, cli, browserContext, athenaClient, messageHandler, fileWatcher, speedKitServiceWorkerJs);
         const extensionBridge = new ExtensionBridge(cli);
-        return new OnboardingService(browserContext, customerConfig, fetchHandler, fileWatcher, cli, messageHandler, extensionBridge);
+        return new OnboardingService(browserContext, customerConfig, fetchHandler, fileWatcher, cli, messageHandler, extensionBridge, speedKitServiceWorkerJs);
     }
     async prepareMessagehandler(athenaClient, files, customerConfig) {
         const messageHandler = new DevtoolsExtensionApi();
@@ -145,7 +146,7 @@ export class OnboardingServiceFactory {
         const configApiContext = new ConfigApiContext(app);
         return new ConfigApiServiceFactory(configApiContext).getService();
     }
-    async getFetchEventHandler(files, customerConfig, documentHandler, cache, cli, browserContext, athenaClient, messageHandler, fileWatcher) {
+    async getFetchEventHandler(files, customerConfig, documentHandler, cache, cli, browserContext, athenaClient, messageHandler, fileWatcher, speedKitServiceWorkerJs) {
         const configApi = this.getConfigApi(customerConfig.app);
         const serverConfig = await this.getSpeedKitServerConfig(configApi, cli);
         const agent = this.getCrawlerAgent(customerConfig, cli);
@@ -162,7 +163,7 @@ export class OnboardingServiceFactory {
             new SpeedKitInstallHtml(customerConfig, browserContext, new InstallSpeedKitHtmlTemplate()),
             new SpeedKitInstallJs(customerConfig, files.getByName(INTEGRATION_FILES.BUILD.INSTALL)),
             new CustomerServiceWorkerJs(customerConfig),
-            new SpeedKitServiceWorkerJs(customerConfig, files.getByName(INTEGRATION_FILES.CUSTOM.SW)),
+            speedKitServiceWorkerJs,
             new DashboardRequest(new Dashboard(customerConfig, parameterQueryBuilder, athenaClient, requestDiffService, new DiffAgainstCurrentPage(DiffService, documentHandler, crawler, cli), cache)),
         ];
         if (this.context.local) {

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

@@ -1,6 +1,7 @@
 import { CustomerConfig } from "../integration-api/index.js";
 import { BrowserContext } from "./onboarding-model.js";
 import { FetchEventHandler } from "./fetch-event-handler.js";
+import { SpeedKitServiceWorkerJs } from "./fetch-events/speed-kit-service-worker-js.js";
 import { FileWatcher } from "./file-events/file-watcher.js";
 import { CliService } from "../cli/index.js";
 import { DevtoolsExtensionApi } from "./browser/extension/devtools-extension-api.js";
@@ -16,8 +17,11 @@ export declare class OnboardingService {
     private cli;
     private developmentToolsMessages;
     private extensionBridge;
+    private speedKitServiceWorkerJs;
     private reinstallOnNextNavigate;
-    constructor(browserContext: BrowserContext, customerConfig: CustomerConfig, fetchEventHandler: FetchEventHandler, fileWatcher: FileWatcher, cli: CliService, developmentToolsMessages: DevtoolsExtensionApi, extensionBridge: ExtensionBridge);
+    private lastForeignSwReinstall;
+    private readonly activatedSwVersions;
+    constructor(browserContext: BrowserContext, customerConfig: CustomerConfig, fetchEventHandler: FetchEventHandler, fileWatcher: FileWatcher, cli: CliService, developmentToolsMessages: DevtoolsExtensionApi, extensionBridge: ExtensionBridge, speedKitServiceWorkerJs: SpeedKitServiceWorkerJs);
     /**
      * Prepare the puppeteer browser, wire event listeners, navigate to the
      * install page, then block until either the caller aborts the signal
@@ -37,6 +41,26 @@ export declare class OnboardingService {
     private attachExtensionBridge;
     private findPage;
     private prepareCleanState;
+    /**
+     * Detects when the DEPLOYED service worker takes over the local session and
+     * repairs it by reinstalling through the install page.
+     *
+     * Chrome's SW update checker fetches the wrapper and its imported sw.js in
+     * the browser process, where CDP Fetch interception does not apply — those
+     * fetches reach production. Because the production wrapper differs from the
+     * locally served one, any update check that slips through installs the
+     * deployed build. With static routing (`activateStaticRouting`), that is no
+     * longer harmless: routes are frozen at install time from the deployed
+     * config, so pages only enabled locally bypass the SW entirely (symptom:
+     * `responseCause: "SwBooting"` on every navigation of those pages).
+     *
+     * Only page-initiated `register()` script fetches are interceptable, so a
+     * version that activates without `SpeedKitServiceWorkerJs` having served
+     * sw.js just before must be a takeover — reinstall via the install page,
+     * which goes through the intercepted path again.
+     */
+    private registerForeignSwGuard;
+    private isForeignSwVersion;
     private reinstallSpeedKit;
     private registerFileWatcher;
     private registerReinstallSpeedKitOnNavigate;

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

@@ -1,6 +1,11 @@
 import puppeteerExtra from "puppeteer-extra";
 import { BROWSER_EVENTS, CDP_SESSION, } from "./onboarding-model.js";
 import { safe } from "../../helpers/safe.js";
+// A SW version activating later than this after the last locally served sw.js
+// cannot originate from our interception — it is a deployed-build takeover.
+const LOCAL_SW_SERVE_GRACE_MS = 10_000;
+// Takeovers can retrigger on every update check — don't reinstall in a tight loop.
+const FOREIGN_SW_REINSTALL_COOLDOWN_MS = 30_000;
 /**
  * Represents the OnboardingService which is responsible for setting up the browser to test a config using Puppeteer.
  */
@@ -12,8 +17,11 @@ export class OnboardingService {
     cli;
     developmentToolsMessages;
     extensionBridge;
+    speedKitServiceWorkerJs;
     reinstallOnNextNavigate = false;
-    constructor(browserContext, customerConfig, fetchEventHandler, fileWatcher, cli, developmentToolsMessages, extensionBridge) {
+    lastForeignSwReinstall = 0;
+    activatedSwVersions = new Set();
+    constructor(browserContext, customerConfig, fetchEventHandler, fileWatcher, cli, developmentToolsMessages, extensionBridge, speedKitServiceWorkerJs) {
         this.browserContext = browserContext;
         this.customerConfig = customerConfig;
         this.fetchEventHandler = fetchEventHandler;
@@ -21,6 +29,7 @@ export class OnboardingService {
         this.cli = cli;
         this.developmentToolsMessages = developmentToolsMessages;
         this.extensionBridge = extensionBridge;
+        this.speedKitServiceWorkerJs = speedKitServiceWorkerJs;
     }
     /**
      * Prepare the puppeteer browser, wire event listeners, navigate to the
@@ -102,6 +111,7 @@ export class OnboardingService {
         });
         await cdpSession.send("Emulation.clearDeviceMetricsOverride");
         await cdpSession.send("Emulation.clearGeolocationOverride");
+        this.registerForeignSwGuard(page, cdpSession);
         safe(() => {
             cdpSession.on(CDP_SESSION.EVENTS.SERVICE_WORKER.REGISTRATION_UPDATED, ({ registrations, }) => {
                 for (const registration of registrations) {
@@ -116,6 +126,65 @@ export class OnboardingService {
             });
         });
     }
+    /**
+     * Detects when the DEPLOYED service worker takes over the local session and
+     * repairs it by reinstalling through the install page.
+     *
+     * Chrome's SW update checker fetches the wrapper and its imported sw.js in
+     * the browser process, where CDP Fetch interception does not apply — those
+     * fetches reach production. Because the production wrapper differs from the
+     * locally served one, any update check that slips through installs the
+     * deployed build. With static routing (`activateStaticRouting`), that is no
+     * longer harmless: routes are frozen at install time from the deployed
+     * config, so pages only enabled locally bypass the SW entirely (symptom:
+     * `responseCause: "SwBooting"` on every navigation of those pages).
+     *
+     * Only page-initiated `register()` script fetches are interceptable, so a
+     * version that activates without `SpeedKitServiceWorkerJs` having served
+     * sw.js just before must be a takeover — reinstall via the install page,
+     * which goes through the intercepted path again.
+     */
+    registerForeignSwGuard(page, cdpSession) {
+        cdpSession.on(CDP_SESSION.EVENTS.SERVICE_WORKER.VERSION_UPDATED, async ({ versions, }) => {
+            for (const version of versions) {
+                if (!this.isForeignSwVersion(version)) {
+                    continue;
+                }
+                this.cli.writeWarning(`${this.cli.style.yellow("Deployed Service Worker took over")} (version ${version.versionId}) — an update check bypassed the local interception. Reinstalling the local build.`);
+                this.developmentToolsMessages.addMessage({
+                    id: "serviceWorker",
+                    data: `Deployed Service Worker took over (version ${version.versionId}); reinstalling the local build`,
+                });
+                if (Date.now() - this.lastForeignSwReinstall <
+                    FOREIGN_SW_REINSTALL_COOLDOWN_MS) {
+                    continue;
+                }
+                this.lastForeignSwReinstall = Date.now();
+                await safe(this.reinstallSpeedKit(page, new URL(page.url()).pathname));
+            }
+        });
+    }
+    isForeignSwVersion(version) {
+        if (version.status !== "activated") {
+            return false;
+        }
+        // Only guard the Speed Kit wrapper; ignore the empty SWs on disabledScopes
+        // and any site-own service workers.
+        if (!version.scriptURL.includes(this.customerConfig.swPath)) {
+            return false;
+        }
+        if (version.scriptURL.includes("empty=1")) {
+            return false;
+        }
+        // Activation events repeat per version (runningStatus changes) — handle each version once.
+        if (this.activatedSwVersions.has(version.versionId)) {
+            return false;
+        }
+        this.activatedSwVersions.add(version.versionId);
+        // A locally served sw.js right before the activation means we installed it.
+        return (Date.now() - this.speedKitServiceWorkerJs.lastServedAt >
+            LOCAL_SW_SERVE_GRACE_MS);
+    }
     async reinstallSpeedKit(page, pathname) {
         const url = new URL(page.url());
         let target = url.href;

package/oclif.manifest.json

@@ -1001,5 +1001,5 @@
       ]
     }
   },
-  "version": "4.20.3"
+  "version": "4.20.5"
 }

package/package.json

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